# Browse table schemas List and retrieve the tables you can query. A `Schema` describes a table you can query: its name, columns, data types, primary keys, and foreign keys. Use schemas to discover tables before you [run a SQL query](https://docs.stripe.com/data/api/query-runs.md), or to find [reports](https://docs.stripe.com/data/api/reports.md) that relate to a table. You can find the tables in the Dashboard’s [Stripe data schema](https://docs.stripe.com/data/schema.md) in the `analytical` dataset. ## Required permissions To list and retrieve schemas, grant **Data** > **Queries** > **Read** (`data_queries_read`) on a [restricted API key](https://dashboard.stripe.com/apikeys). ## List schemas List the tables available in a dataset. The list endpoint accepts these optional parameters: - `name`: Filters the results to a specific table name. - `dataset`: Filters the results to a specific dataset. A dataset is a set of tables that can be queried together. The supported dataset is `analytical`. - `limit`: Specifies the number of schemas to return per page. Defaults to 10, and can be between 1 and 1,000. - `include[0]=columns`: Returns the columns along with other schema metadata. Due to their size, columns are only returned by default from the retrieve endpoint. ```curl curl -G https://api.stripe.com/v2/data/schemas \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-09-30.preview" \ -d dataset=analytical \ -d "include[0]=columns" ``` ```json { "object": "v2.list", "data": [ { "id": "schema_61VNxLFc4hQhyG5lS5", "object": "v2.data.schema", "name": "balance_transactions", "dataset": "analytical", "description": "Funds moving through your Stripe account.", "livemode": true, "refreshed_at": "2026-09-14T19:19:39.000Z", "columns": [ { "name": "id", "description": "Unique identifier for the balance transaction.", "type": "varchar", "is_primary_key": true, "foreign_keys_from": [], "foreign_keys_to": [] }, { "name": "amount", "description": "Amount of the transaction, in the currency's smallest unit.", "type": "bigint", "is_primary_key": false, "foreign_keys_from": [], "foreign_keys_to": [] } ], "relevant_reports": [] } ], "next_page_url": null, "previous_page_url": null } ``` To fetch one table by name: ```curl curl -G https://api.stripe.com/v2/data/schemas \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-09-30.preview" \ -d dataset=analytical \ -d name=balance_transactions ``` ## Retrieve a schema Retrieve a schema by ID when you already have it from a list response or from a column’s foreign-key reference. ```curl curl https://api.stripe.com/v2/data/schemas/schema_61VNxLFc4hQhyG5lS5 \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-09-30.preview" ``` ```json { "id": "schema_61VNxLFc4hQhyG5lS5", "object": "v2.data.schema", "name": "balance_transactions", "dataset": "analytical", "description": "Funds moving through your Stripe account.", "extended_description": "Each row is a balance transaction that credits or debits your Stripe balance.", "livemode": true, "refreshed_at": "2026-09-14T19:19:39.000Z", "columns": [ { "name": "id", "description": "Unique identifier for the balance transaction.", "type": "varchar", "is_primary_key": true, "foreign_keys_from": [], "foreign_keys_to": [] }, { "name": "source_id", "description": "ID of the Stripe object that created this transaction.", "type": "varchar", "is_primary_key": false, "foreign_keys_from": [], "foreign_keys_to": [ { "schema": "schema_61ChargesExample01", "column": "id" } ] } ], "relevant_reports": [ { "id": "report_61Sud3n5oAGVCWiSr5", "name": "balance.summary", "description": "Your starting balance, activity, payouts and ending balance for the date range. Amounts are based on when transactions affected your Stripe balance. Use this summary report like a bank statement to reconcile your opening balance to your closing balance." } ] } ``` Each schema has the following: - `name` - `dataset` - `description` - `livemode` - `refreshed_at`: When the table was most recently updated. - `columns`: Only included from the list endpoint if requested. A schema may have the following: - `relevant_reports`: A list of Stripe-defined reports that use this table. - `extended_description`: Additional detail to help you write queries. Each column in `columns` includes: - `name` - `description` - `type`: One of `varchar`, `bigint`, `boolean`, `timestamp`, `double`, `integer`, or `decimal`. - `is_primary_key`: Whether this column is part of a schema’s primary key. - `foreign_keys_to`: Columns in other schemas this column references. - `foreign_keys_from`: Columns in other schemas that reference this column. ## Run a query or report from a schema After you have a table name and columns: - [Create a query run](https://docs.stripe.com/data/api/query-runs.md) with a `query.sql` that selects from `schema.name`. - [Create a report run](https://docs.stripe.com/data/api/reports.md) for a report listed in `relevant_reports`. ```curl curl -X POST https://api.stripe.com/v2/data/query_runs \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-09-30.preview" \ --json '{ "query": { "sql": "SELECT id, amount, currency FROM balance_transactions LIMIT 10" }, "dataset": "analytical", "format": "csv" }' ``` ## Use an Organization API key The Schema API accepts [Organization API keys](https://docs.stripe.com/keys/organization-api-keys.md). Omit `Stripe-Context` to list schemas for the organization. Set [Stripe-Context](https://docs.stripe.com/context.md) to list schemas for one account. ## See also - [Access Stripe data with the API](https://docs.stripe.com/data/api.md) - [Run a SQL query](https://docs.stripe.com/data/api/query-runs.md) - [Run a report](https://docs.stripe.com/data/api/reports.md) - [Stripe data schema](https://docs.stripe.com/data/schema.md)