Menu

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

WhereDo this
A starterThe user runs its setup in their own terminal and pastes the key there. It writes .env
Your own projectThe user saves it as INSEEQ_API_KEY in .env. Check .env is in .gitignore before anything else
DeployedAdd 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.

Command line
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:

Command line
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.

Command line
curl -s https://api.inseeq.com/v1/status -H "Authorization: Bearer $INSEEQ_API_KEY"
JSON
{
  "refreshed_at": "2026-11-06T06:42:11+00:00",
  "build_mode": "daily",
  "stale_sources": [],
  "data_version": "9f2c41ab77d0e310",
  "last_failure": null,
  "sources": []
}
FieldMeaning
refreshed_atWhen 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_modedaily, weekly, on_demand or null
stale_sourcesSource platforms that were behind in that build
data_versionChanges 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
sourcesOne 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:

AnswerMeaningDo this
401 invalid_keyThe key is missing, unknown or revokedCheck the variable is set and the header is Authorization: Bearer <key>. Only then tell the user they need a new key
401 wrong_key_typeThis is an inseeq MCP key or a login token, not an API keyThe 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_enabledThe Data API is not on for this organizationThe user asks their assistant to tell inseeq, or asks through their usual channel
409 importingThe organization's data is not ready yetTry again later

List the tables

Command line
curl -s "https://api.inseeq.com/v1/tables?limit=50" -H "Authorization: Bearer $INSEEQ_API_KEY"
JSON
{
  "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

Command line
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.

FieldMeaning
primary_keyThe columns that make one row unique, or null when not stated
piiOn the table: it holds personal data. On a column: that column is personal data
unitcurrency_major, cents, micros, count, ratio or share, or null. Convert cents and micros before showing money
additivefalse: 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

Command line
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:

CodeWhat
not_selectDML, DDL, scripts, several statements, call
use_metadata_toolsINFORMATION_SCHEMA, __TABLES__
refused_functionsession_user(), system variables (@@), external queries, ML and AI functions
table_not_publishedAny 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.

typevalue, always a JSON string
STRINGAny 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 typeJSON value
INTEGER, FLOATNumber. A non-finite float is the string "nan", "inf" or "-inf"
BOOLEANtrue or false
STRINGString
NUMERIC, BIGNUMERICString, trimmed: 1.50 arrives as "1.5". Parse it before you add
DATE, TIME, DATETIMEISO 8601 string
TIMESTAMPISO 8601 string with an offset
BYTESHex string
RECORD and repeated columnsObjects and arrays of the above
Anythingnull 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:

FieldMeaning
row_countRows on this page
total_rowsRows in the whole result
next_cursorNull on the last page
data_version, refreshed_atThe data this answer was read from
cachedtrue: answered from the API's cache, with no scan and no budget spent
bytes_processedBytes 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.

Command line
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-Cached and X-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 STRING column, 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.

Command line
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: false and bytes_processed: 0. Later pages cost nothing.
  • Pages keep the max_rows of the first call.
  • A refresh does not disturb a walk. Every page reads the same snapshot and reports the data_version and refreshed_at of the first page.
  • Add order by if 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_large means one row is over 1 MiB, so the walk cannot pass it. Select fewer columns.

Limits

LimitValueAnswer
Calls per key10 a second, burst 100429 rate_limited, with Retry-After
Queries running per organization10, then a wait of up to 25 seconds429 busy, with Retry-After
Scan per query5 GiB413 over_bytes_cap
Run time per query30 seconds504 timeout
Query budget per organization200 GiB billed a day, reset at 00:00 UTC. A small query bills at least 10 MiB per table429 over_daily_budget, with resets_at and Retry-After
Webhooks per organization5, disabled ones included409 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.

Next

Quickstart · inseeq Data API