QuickstartBeta
From a key to your first query. The API is read-only: nothing here can change the client's data.
Get a key
There are two ways, and both show the key once.
- On the web: the user presses Get a key on docs.inseeq.com/data-api/quickstart, signs in, picks the workspace if they belong to more than one, chooses API key, and copies the key.
- In a chat: the user asks Claude, with the inseeq connector, to create an API key. The tool is
create_api_key, and it takes a label such as "Sales dashboard". It answers a one-time link that works once, for 10 minutes. If the link has expired, they ask for a new one.
If you are the agent, send the user to the web page or give them the link as it is. Do not open, fetch or preview the link. The key is for the user's environment, not for you or a chat.
Any member of the organization can create keys, and an inseeq operator can create one for them. An organization holds up to 10 keys and can ask for 20 links in 24 hours. Keys belong to the organization, so a person leaving does not end one.
To replace a key: create a second one, swap it in, then revoke the first with revoke_api_key. list_api_keys shows what exists.
Where the key lives
| Where | Do this |
|---|---|
| A starter | The user runs its setup in their own terminal and pastes the key there. It writes .env |
| Your own project | The user saves it as INSEEQ_API_KEY in .env. Check .env is in .gitignore before anything else |
| Deployed | Add INSEEQ_API_KEY in the host's environment settings |
Stop and ask the user to do these steps themselves. Never ask for the key in a chat. You may load .env into a process, as below. Never display its values: no cat, no echo, nothing that puts them in a chat or a log.
Never give the variable a name your framework sends to the browser, such as NEXT_PUBLIC_ or VITE_. The API sends no CORS headers, so a browser cannot call it anyway. Call it from your server.
Start a project
New project: start from a starter and make a private copy. A fork of a public repo stays public, and a client's copy must be private.
gh repo create my-dashboard --template inseeq/nextjs-starter --private --clone
# or
gh repo create my-dashboard --template inseeq/python-starter --private --clone
Without gh, use "Use this template" on the repo page and choose private. The starters are TypeScript on Next.js and Python on FastAPI. The README in each one says how to run setup.
Existing project: add INSEEQ_API_KEY to the environment and copy the client from dashboards. You need no SDK.
Check the key
In a starter, setup already made this check and the app loads .env itself, so leave .env alone. In your own project, the commands below read INSEEQ_API_KEY from your shell. If it lives in .env, load it, never display it, and confirm it is set:
set -a; . ./.env; set +a
test -n "$INSEEQ_API_KEY" && echo "key is set"
An unset variable answers invalid_key, so check this before you tell the user the key is bad.
curl -s https://api.inseeq.com/v1/status -H "Authorization: Bearer $INSEEQ_API_KEY"
{
"refreshed_at": "2026-11-06T06:42:11+00:00",
"build_mode": "daily",
"stale_sources": [],
"data_version": "9f2c41ab77d0e310",
"last_failure": null,
"sources": []
}
| Field | Meaning |
|---|---|
refreshed_at | When the newest successful data build finished. Null before the first one is seen. This is the age of the data, not the time of your call |
build_mode | daily, weekly, on_demand or null |
stale_sources | Source platforms that were behind in that build |
data_version | Changes when a refresh lands or the published tables change. Null for a new organization until the first check, and then nothing is cached |
last_failure | {failed_at} when the newest build failed, else null. The last good data stays readable |
sources | One row per source, plus one row per kind of evidence the client should have but does not: platform, evidence_type, evidence_label, coverage_status, data_from_native, data_through_native, final_through_native, provisional_days, is_stale, last_success_at_utc, last_run_status. coverage_status is measured, partial, stale or not_collected. On a not_collected row only evidence_type, evidence_label and coverage_status are set: platform and the rest are null |
Timestamps here and on query answers look like 2026-11-06T06:42:11+00:00. Those in events look like 2026-11-06T06:45:02Z. In JavaScript, new Date(value) reads both. In Python, datetime.fromisoformat refuses Z before 3.11, so use datetime.fromisoformat(value.replace("Z", "+00:00")).
Key errors:
| Answer | Meaning | Do this |
|---|---|---|
401 invalid_key | The key is missing, unknown or revoked | Check the variable is set and the header is Authorization: Bearer <key>. Only then tell the user they need a new key |
401 wrong_key_type | This is an inseeq MCP key or a login token, not an API key | The user creates an API key on the web or in Claude. MCP keys never work here, and API keys never work on the MCP |
403 not_enabled | The Data API is not on for this organization | The user asks their assistant to tell inseeq, or asks through their usual channel |
409 importing | The organization's data is not ready yet | Try again later |
List the tables
curl -s "https://api.inseeq.com/v1/tables?limit=50" -H "Authorization: Bearer $INSEEQ_API_KEY"
{
"tables": [
{
"name": "example_daily",
"type": "table",
"description": "One sentence on what this holds.",
"grain": "One row per day.",
"date_column": "day",
"date_from": "2025-01-01",
"date_to": "2026-11-05",
"row_count": 675,
"last_updated": "2026-11-06T06:40:02+00:00"
}
],
"next_after": null
}
limit is 1 to 100, default 50. While next_after is not null, send it back as after. type is table or view. All names in these docs are made up. Each organization has its own tables, and they change, so read them at run time or re-read them when you build.
Read a table's docs
curl -s https://api.inseeq.com/v1/tables/example_daily -H "Authorization: Bearer $INSEEQ_API_KEY"
This answers name, type, description, row_count, last_updated, date_column, date_from, date_to, primary_key, pii and columns: [{name, type, description, unit, additive, pii}]. The date fields are null on a table with no date column.
| Field | Meaning |
|---|---|
primary_key | The columns that make one row unique, or null when not stated |
pii | On the table: it holds personal data. On a column: that column is personal data |
unit | currency_major, cents, micros, count, ratio or share, or null. Convert cents and micros before showing money |
additive | false: never sum this column across rows or days (a ratio, a running total). Null when not stated |
The listing's description is one sentence. This one is the full text with the caveats. Read it before you sum anything: it says what a row is and what is safe to add up.
Run a query
curl -s -X POST https://api.inseeq.com/v1/query \
-H "Authorization: Bearer $INSEEQ_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"sql": "select day, sum(amount) as amount from example_daily where day >= @since group by day order by day",
"params": [{ "name": "since", "type": "DATE", "value": "2026-10-01" }],
"max_rows": 1000
}'
SQL: BigQuery GoogleSQL. One select, which may start with with. Name tables with no dataset or project, as the listing does. Naming a dataset answers table_not_published.
Refused:
| Code | What |
|---|---|
not_select | DML, DDL, scripts, several statements, call |
use_metadata_tools | INFORMATION_SCHEMA, __TABLES__ |
refused_function | session_user(), system variables (@@), external queries, ML and AI functions |
table_not_published | Any table not on GET /v1/tables, including a mistyped name |
A mistyped column answers 400 bigquery_error, and its message names the column. It is your SQL, not an outage. Fix it and do not retry.
Params: BigQuery named parameters, @name in the SQL.
type | value, always a JSON string |
|---|---|
STRING | Any text |
INT64 | "42" |
FLOAT64 | "12.5". Must be finite |
BOOL | "true" or "false", lowercase |
DATE | "2026-10-01" |
TIMESTAMP | "2026-10-01T12:00:00Z". No zone means UTC |
Names are letters, digits and _, not starting with a digit, and unique ignoring case. There are no array params: for a list, pass one string and use unnest(split(@ids)). A param in the SQL that you did not send answers bigquery_error.
Answer values:
| Column type | JSON value |
|---|---|
INTEGER, FLOAT | Number. A non-finite float is the string "nan", "inf" or "-inf" |
BOOLEAN | true or false |
STRING | String |
NUMERIC, BIGNUMERIC | String, trimmed: 1.50 arrives as "1.5". Parse it before you add |
DATE, TIME, DATETIME | ISO 8601 string |
TIMESTAMP | ISO 8601 string with an offset |
BYTES | Hex string |
RECORD and repeated columns | Objects and arrays of the above |
| Anything | null when the value is null |
columns[].type uses INTEGER, FLOAT and BOOLEAN. params takes INT64, FLOAT64 and BOOL. They are the same types under different names.
Integers past 2^53 lose precision on the way through JSON: 9007199254740993 arrives as 9007199254740992, and our own server does this before you see it. Cast long IDs in the SQL: select cast(id as string) as id.
The rest of the answer:
| Field | Meaning |
|---|---|
row_count | Rows on this page |
total_rows | Rows in the whole result |
next_cursor | Null on the last page |
data_version, refreshed_at | The data this answer was read from |
cached | true: answered from the API's cache, with no scan and no budget spent |
bytes_processed | Bytes scanned. 0 on a cached answer. It can also be 0 with cached: false when BigQuery's own cache served the job |
CSV
Add "format": "csv" to the body of POST /v1/query, and &format=csv to each GET /v1/query/results call. The cursor does not remember the format.
curl -s -X POST https://api.inseeq.com/v1/query -D headers.txt -o page1.csv \
-H "Authorization: Bearer $INSEEQ_API_KEY" -H 'Content-Type: application/json' \
-d '{"sql": "select day, amount from example_daily", "format": "csv"}'
- The body is
text/csv; charset=utf-8, RFC 4180, with CRLF line ends and a header row on every page. - The JSON fields move to headers:
X-Row-Count,X-Total-Rows,X-Next-Cursor(absent on the last page),X-Data-Version,X-Refreshed-At,X-CachedandX-Bytes-Processed. - Null is an empty field. An empty string is
"". Records and arrays are JSON text. Numbers and booleans are as in JSON. - In a
STRINGcolumn, a value that starts with=,+,-,@, a tab or a carriage return gets a'in front. Sheets and Excel would run it as a formula, and rows hold text written by other people. Number columns are never changed, so negative amounts stay numbers. - Errors stay JSON, with their usual status.
- A CSV answer and a JSON answer share one cache entry, so asking for both costs one scan.
More than one page
max_rows is 1 to 5,000, default 1,000. A page also stops at 1 MiB, so row_count can be below max_rows.
curl -s -G https://api.inseeq.com/v1/query/results \
--data-urlencode "cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer $INSEEQ_API_KEY"
- A cursor is about 570 characters. URL-encode it.
- A page answers the same fields as a query, with
cached: falseandbytes_processed: 0. Later pages cost nothing. - Pages keep the
max_rowsof the first call. - A refresh does not disturb a walk. Every page reads the same snapshot and reports the
data_versionandrefreshed_atof the first page. - Add
order byif you need an order. Paging keeps whatever order the result has. - On 410
cursor_expired, run the query again from the start. Results last about a day, and a cursor over 12 hours old can expire. Never store one. - 413
row_too_largemeans one row is over 1 MiB, so the walk cannot pass it. Select fewer columns.
Limits
| Limit | Value | Answer |
|---|---|---|
| Calls per key | 10 a second, burst 100 | 429 rate_limited, with Retry-After |
| Queries running per organization | 10, then a wait of up to 25 seconds | 429 busy, with Retry-After |
| Scan per query | 5 GiB | 413 over_bytes_cap |
| Run time per query | 30 seconds | 504 timeout |
| Query budget per organization | 200 GiB billed a day, reset at 00:00 UTC. A small query bills at least 10 MiB per table | 429 over_daily_budget, with resets_at and Retry-After |
| Webhooks per organization | 5, disabled ones included | 409 webhook_limit |
A cached answer, GET /v1/tables, GET /v1/status and later pages of a query spend no budget, so they keep working when it runs out.
After rate_limited or busy, wait for Retry-After, add jitter and retry. Stop after a few tries and show the error: busy can last longer than one wait. over_daily_budget will not clear before resets_at.
busy covers BigQuery's short faults too. bigquery_error does not: it means the query itself was refused, so a retry fails the same way.