# Search data resources

Find schemas, metrics, and reports that help answer your questions.

Use the Data Search API when you know the question you want to answer but not which table, metric, or report to use. The Data Search API returns ranked resource metadata, not query results. It doesn’t execute SQL or reports.

### Request to join the preview for the Data Search API.

Enter your email to request access.

```bash
curl https://docs.stripe.com/preview/register \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Referer: https://docs.stripe.com/data/api/search" \
  -d '{"email": "EMAIL", "preview": "analytics_core_eng_preview"}'
```

## Search for resources 

Authenticate searches with your API key, and set the `Stripe-Version` header to `2026-10-14.preview` or a later preview version. Search doesn’t require a specific API key permission. The APIs you use to query a discovered schema, metric, or report still require their own permissions.

Search returns only resources your account can access, so results differ between accounts. Metric results require access to the [Analytics API](https://docs.stripe.com/data/analytics.md) preview. Within each catalog, some tables, metrics, and reports are available only to certain accounts.

Send your question in `query`. To narrow the search, set `catalogs` to one or more of `schemas`, `metrics`, or `reports`. Learn about [schemas and reports](https://docs.stripe.com/data/api.md#concepts) and [metrics](https://docs.stripe.com/data/analytics.md#concepts). Omit `catalogs` to search all three.

Set `limit` to the maximum number of matches you want. It defaults to 5 and accepts values from 1 to 20. Search returns a single page.

The following request searches schemas and reports:

```bash
curl https://api.stripe.com/v2/data/operations/search \
  -H "Authorization: Bearer {{SECRET_KEY}}" \
  -H "Stripe-Version: 2026-10-14.preview" \
  --json '{
    "query": "Which tables and reports show failed card payments by decline reason?",
    "catalogs": ["schemas", "reports"],
    "limit": 2
  }'
```

The following illustrative response shows one schema match. Results vary with your question and access. Results are ordered by `relevance_score`, a relative value from 0 to 1. Use it to compare results in one response, not as a fixed threshold.

```json
{
  "object": "v2.data.search_result_list",
  "data": [
    {
      "id": "table_test_xxx",
      "object_type": "v2.data.schema",
      "catalog": "schemas",
      "name": "charges",
      "description": "One row per charge, including the outcome and decline reason for failed card payments.",
      "relevance_score": "0.92",
      "refreshed_at": "2025-01-15T00:00:00.000Z",
      "reference_url": "/v2/data/schemas/table_test_xxx",
      "execution_spec": {
        "id": "charges",
        "execution_url": "/v2/data/query_runs",
        "http_method": "POST"
      },
      "schemas": {
        "dataset": "analytical",
        "columns": [
          {
            "name": "id",
            "description": "The unique identifier of the charge.",
            "type": "varchar",
            "is_primary_key": true,
            "foreign_keys_from": [],
            "foreign_keys_to": []
          }
        ],
        "relevant_reports": []
      }
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}
```

When your question matches a known analytics topic, such as recurring revenue, the response also includes `context` with guidance and definitions of related business concepts. Otherwise, `context` is `null`.

## Choose a query workflow 

Inspect each result’s description and catalog-specific metadata before choosing a resource. Use its retrieval URL, when available, to inspect the complete resource. Metric results don’t have a retrieval URL.

Choose the workflow that matches the result:

- **Schema**: Inspect the table and columns, then [create a query run](https://docs.stripe.com/data/api/query-runs.md) with SQL. A schema identifier isn’t SQL. The execution identifier is the table name to use in your query. Query runs require the Queries Read permission (`data_queries_read`).
- **Metric**: Inspect the metric and its dimensions, then query it through the [Analytics API](https://docs.stripe.com/data/analytics.md). Metric queries require the Metrics Read permission (`data_metrics_read`).
- **Report**: Check the required parameters, then [create a report run](https://docs.stripe.com/data/api/reports.md). Report runs require the Reports Read permission (`data_reports_read`).

The execution instructions identify the follow-up API, but aren’t a complete request body. Follow that API’s guide to construct the request. You need the access and permissions required by that API. Finding a resource doesn’t grant permission to query it. Follow [best practices for managing secret keys](https://docs.stripe.com/keys-best-practices.md) when making API requests.

## Use the Stripe MCP 

You can search from an AI agent or code editor with the `stripe_discovery` tool in the [Stripe Model Context Protocol (MCP) server](https://docs.stripe.com/mcp.md). The tool calls the Data Search API for you, so you can describe the data you’re looking for in natural language. Your agent can then run what it finds with the `stripe_analytics` and `stripe_reports` tools.

To get set up, [connect your AI agent](https://docs.stripe.com/data/analyze-with-ai.md#connect) to the Stripe MCP server. The `stripe_discovery` tool doesn’t require a specific permission, but the tools that run results require the permissions for their APIs.

## Refine your search 

If you don’t find a match, make your question more specific or try another catalog. Empty results don’t prove that your account has no relevant data. Search omits resources your account can’t access, including all metrics without Analytics API preview access.