# Create a Query Run

Creates a query run to execute ad-hoc SQL and returns a `QueryRun` object to track progress and retrieve results.

## Request

```curl
curl -X POST https://api.stripe.com/v2/data/reporting/query_runs \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "sql": "select * from balance_transactions limit 10"
  }'
```

### Response

```json
{
  "created": "2025-08-26T00:00:00.000Z",
  "id": "qryrun_test_xxx",
  "object": "v2.data.reporting.query_run",
  "sql": "select * from balance_transactions limit 10",
  "result": null,
  "result_options": {
    "compress_file": false
  },
  "status": "running",
  "status_details": {},
  "livemode": false
}
```

## Parameters

- `sql` (string, required)
  The SQL to execute.

- [`result_options`](https://docs.stripe.com/api/v2/data/reporting/query-runs/create.md?query=result_options&api-version=2026-04-22.preview) (object, optional)
  Optional settings to customize the results of the `QueryRun`.

## Returns

## Response attributes

- `id` (string)
  The unique identifier of the `QueryRun` object.

- `object` (string, value is "v2.data.reporting.query_run")
  String representing the object’s type. Objects of the same type share the same value of the object field.

- `created` (timestamp)
  Time at which the object was created.

- `livemode` (boolean)
  Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.

- [`result`](https://docs.stripe.com/api/v2/data/reporting/query-runs/create.md?query=result&api-version=2026-04-22.preview) (object, nullable)
  Details how to retrieve the results of a successfully completed `QueryRun`.

- [`result_options`](https://docs.stripe.com/api/v2/data/reporting/query-runs/create.md?query=result_options&api-version=2026-04-22.preview) (object, nullable)
  The options specified for customizing the output of the `QueryRun`.

- `sql` (string)
  The SQL that was executed.

- `status` (enum)
  The current status of the `QueryRun`.
Possible enum values:
  - `failed`
    Query has failed to complete due to an error.

  - `running`
    Query is in progress.

  - `succeeded`
    Query has successfully completed.

- `status_details` (map)
  Additional details about the current state of the `QueryRun`. Populated when the `QueryRun`

  is in the `failed` state, providing more information about why the query failed.

## Error Codes

| HTTP status code | Code | Description |
| --- | --- | --- |
| 400 | query_run_invalid_sql | Returned when the SQL in a query run request is invalid. |
| 403 | query_run_api_inaccessible | Returned when the query runs API is not accessible to the request. The error message provides the reason (e.g. feature not enabled, compartment not allowed). |
| 429 | query_run_rate_limit_exceeded | Returned when an API key has reached its limit of concurrently running query runs. Wait for existing query runs to complete before retrying the request. |