Sigma API OverviewPrivate preview

Learn more about the Sigma API.

Using the Sigma API, you can programmatically save and execute queries.

Get started

First, create a restricted API key for the Sigma API.

This example runs a query immediately:

Command Line
curl https://api.stripe.com/v1/sigma/query_runs -X POST -d sql="SELECT * FROM balance_transactions LIMIT 10" -H "Authorization: Bearer ${SIGMA_API_KEY}"

The response might look like the following. Use the returned ID to check the query run’s status.

{
  "id": "qry_0RHnkR589O8KAxCGsLQqzkd0",
  "object": "sigma.sigma_query_run",
  "created": 1745593263,
  "error": null,
  "finalized_at": null,
  "livemode": true,
  "result": {
    "file": null
  },
  "sql": "SELECT * FROM balance_transactions LIMIT 10",
  "status": "running"
}

To determine whether a query run is complete, retrieve it and check its status:

Command Line
curl https://api.stripe.com/v1/sigma/query_runs/qry_0RHnkR589O8KAxCGsLQqzkd0 -X GET -H "Authorization: Bearer ${SIGMA_API_KEY}"

If the query run is complete and results are available, its status is succeeded and its result.file property contains a File ID:

{
  "id": "qry_0RHnkR589O8KAxCGsLQqzkd0",
  "object": "sigma.sigma_query_run",
  "created": 1745593263,
  "error": null,
  "finalized_at": 1745593273,
  "livemode": true,
  "result": {
    "file": "file_0RHnkb589O8KAxCGYVDkVc5V"
  },
  "sql": "SELECT * FROM balance_transactions LIMIT 10",
  "status": "succeeded"
}

To download the results, use the File ID to GET /v1/files/:id/contents/:

Command Line
curl --output file_0RHnkb589O8KAxCGYVDkVc5V.csv https://files.stripe.com/v1/files/file_0RHnkb589O8KAxCGYVDkVc5V/contents -X GET -H "Authorization: Bearer ${SIGMA_API_KEY}"

A local CSV file with the name you specified using --output contains the results.

Saved queries

To create, retrieve, update, or delete a saved query, interact with the Saved Query resource using the /v1/sigma/saved_queries and /v1/sigma/saved_queries/:id endpoints.

To create a saved query, POST to /v1/sigma/saved_queries. In the sql parameter, provide a query using the same syntax as in the Sigma query editor. The response includes the ID of the new query.

Command Line
curl https://api.stripe.com/v1/sigma/saved_queries -X POST -d sql="SELECT * FROM balance_transactions LIMIT 10" -H "Authorization: Bearer ${SIGMA_API_KEY}"

To update a saved query, POST to /v1/sigma/saved_queries/:id. In the sql parameter, provide a new query to replace the existing one.

Command Line
curl https://api.stripe.com/v1/sigma/saved_queries/qfl_0RHnkR589O8KAxCGsLQqzkd0 -X POST -d sql="SELECT * FROM balance_transactions WHERE created >= timestamp '2025-04-01' LIMIT 10" -H "Authorization: Bearer ${SIGMA_API_KEY}"

To retrieve a saved query, GET /v1/sigma/saved_queries/:id.

Command Line
curl https://api.stripe.com/v1/sigma/saved_queries/qfl_0RHnkR589O8KAxCGsLQqzkd0 -X GET -H "Authorization: Bearer ${SIGMA_API_KEY}"

To delete a saved query, DELETE /v1/sigma/saved_queries/:id.

Command Line
curl https://api.stripe.com/v1/sigma/saved_queries/qfl_0RHnkR589O8KAxCGsLQqzkd0 -X DELETE -H "Authorization: Bearer ${SIGMA_API_KEY}"

Query runs

To run a saved query or retrieve the status of a Query Run, use the /v1/sigma/query_runs and /v1/sigma/query_runs/:id endpoints.

You can also run a query by passing it directly to this endpoint.

Note

Responses to query run requests contain the ID of the query run, not the saved query.

To run a saved query, POST to /v1/sigma/query_runs and provide the saved query’s ID in the from_saved_query parameter.

Command Line
curl https://api.stripe.com/v1/sigma/query_runs -X POST -d from_saved_query="qfl_0RHnRX589O8KAxCGD5v78Gn4" -H "Authorization: Bearer ${SIGMA_API_KEY}"

To run a query directly, POST to /v1/sigma/query_runs. In the sql parameter, provide a query using the same syntax as in the Sigma query editor.

Command Line
curl https://api.stripe.com/v1/sigma/query_runs -X POST  -d sql="SELECT * FROM balance_transactions LIMIT 10" -H "Authorization: Bearer ${SIGMA_API_KEY}"

Download query run results

A successfully created query run has a status of running:

{
  "id": "qry_0RHnkR589O8KAxCGsLQqzkd0",
  "object": "sigma.sigma_query_run",
  "created": 1745593263,
  "error": null,
  "finalized_at": null,
  "livemode": true,
  "result": {
    "file": null
  },
  "sql": "SELECT * FROM balance_transactions LIMIT 10",
  "status": "running"
}

To determine whether a query run is complete, retrieve it and check its status:

Command Line
curl https://api.stripe.com/v1/sigma/query_runs/qry_0RHnkR589O8KAxCGsLQqzkd0 -X GET -H "Authorization: Bearer ${SIGMA_API_KEY}"

If the query run is complete and results are available, its status is succeeded and its result.file property contains a File ID:

{
  "id": "qry_0RHnkR589O8KAxCGsLQqzkd0",
  "object": "sigma.sigma_query_run",
  "created": 1745593263,
  "error": null,
  "finalized_at": 1745593273,
  "livemode": true,
  "result": {
    "file": "file_0RHnkb589O8KAxCGYVDkVc5V"
  },
  "sql": "SELECT * FROM balance_transactions LIMIT 10",
  "status": "succeeded"
}

To download the results, use the File ID to GET /v1/files/:id/contents/:

Command Line
curl --output file_0RHnkb589O8KAxCGYVDkVc5V.csv https://files.stripe.com/v1/files/file_0RHnkb589O8KAxCGYVDkVc5V/contents  -X GET -H "Authorization: Bearer ${SIGMA_API_KEY}"

A local CSV file with the name you specified using --output contains the results.