# 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-07-29.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-07-29.preview) (object, optional)
  Optional settings to customize the results of the `QueryRun`.

## Returns

Returns a [Query Run object](https://docs.stripe.com/api/v2/data/reporting/query-runs/object.md?api-version=2026-07-29.preview).

## 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. |