# Quickstart

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](https://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.

```bash
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](https://github.com/inseeq/nextjs-starter) and [Python on FastAPI](https://github.com/inseeq/python-starter). 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](https://api.inseeq.com/docs/dashboards.md). 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:

```bash
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.

```bash
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": []
}
```

| 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

```bash
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

```bash
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

```bash
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.

```bash
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`.

```bash
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

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

## Next

- [Rules and error codes](https://api.inseeq.com/llms.txt)
- [Build a dashboard](https://api.inseeq.com/docs/dashboards.md)
- [Build an automation](https://api.inseeq.com/docs/automations.md)
- [Handle a table change](https://api.inseeq.com/docs/changes.md)
- [Full contract](https://api.inseeq.com/openapi.json)
