# Export API

> Pull your Dimensions out of Dimension Labs into your own systems, by integration and date range.

The Export API returns the enrichments (your Dimensions) for one or more integrations over a date range, as a zip file with the enrichments by day. Use it to load your Dimensions into a warehouse, a BI tool or your own application.

Base URL: `https://api.dimensionlabs.io`

## Your Export API key

Export API keys are in the **Settings** menu of the app. This is a different key from a source's tracker key (the one in `DL_API_KEY` on the [universal API](/api/tracker#your-api-key) page). The examples read it from `DL_EXPORT_KEY`.

Every request sends the key in the `Authorization` header. A key that isn't valid for the integrations you ask for returns `403`.

You also need the **integration ID** of each source you want to export. If you can't find it, email support@dimensionlabs.io with the source's name.

## Export

```http
GET https://api.dimensionlabs.io/export?startDate=2026-09-01&endDate=2026-10-01&botIds=12345&promptNames=support_ticket_info
Authorization: <your Export API key>
```

Fetches the enrichments for the listed integrations between the two dates. `promptNames` is an optional filter: with it, only those prompts' Dimensions come back.

| Parameter | In | Required | Description |
|---|---|---|---|
| `Authorization` | header | Yes | Your Export API key, from **Settings** |
| `startDate` | query | Yes | Start of the range, inclusive. `YYYY-MM-DD` or Unix milliseconds. |
| `endDate` | query | Yes | End of the range, exclusive. `YYYY-MM-DD` or Unix milliseconds. |
| `botIds` | query | Yes | Comma-separated integration IDs, for example `12345,12346` |
| `promptNames` | query | No | Comma-separated prompt names, to export only those prompts |

Because `endDate` is exclusive, `startDate=2026-09-01&endDate=2026-10-01` covers all of September.

### With curl

```bash
curl -H "Authorization: $DL_EXPORT_KEY" \
  "https://api.dimensionlabs.io/export?startDate=2026-09-01&endDate=2026-10-01&botIds=12345"
```

### Responses

| Status | Body | Meaning |
|---|---|---|
| `200` | `{ "zipFile": "..." }` | The export: a zip of the enrichments, by day. `zipFile` is always present. |
| `403` | `{ "message": "..." }` | Forbidden: the key isn't valid for one of the integrations. `message` says what went wrong. |

### Save the zip

```js
// export.mjs. Node 18 or later. DL_EXPORT_KEY is your Export API key; DL_INTEGRATION_ID is the source's integration ID.


export async function exportDimensions({ startDate, endDate, integrationIds = process.env.DL_INTEGRATION_ID }) {
  const params = new URLSearchParams({ startDate, endDate, botIds: integrationIds });
  const res = await fetch(`https://api.dimensionlabs.io/export?${params}`, { headers: { Authorization: process.env.DL_EXPORT_KEY } });
  if (!res.ok) throw new Error(`Export returned ${res.status}: ${await res.text()}`);
  const { zipFile } = await res.json();
  // zipFile is either a download link or the zip itself as base64 text; this handles both.
  const zip = /^https?:\/\//.test(zipFile)
    ? Buffer.from(await (await fetch(zipFile)).arrayBuffer())
    : Buffer.from(zipFile, 'base64');
  const path = `dimensions-${startDate}-to-${endDate}.zip`;
  await writeFile(path, zip);
  return path;
}
```

Unzip it (`unzip dimensions-2026-09-01-to-2026-10-01.zip -d dimensions/`) and you have the enrichments, one set per day. Open one day's file before you build a table on it, and match your table's columns to what you find. The [warehouse guides](/integrations/warehouses) load these files into Snowflake, BigQuery, Databricks and Redshift.

## Index

```http
GET https://api.dimensionlabs.io/index
Authorization: <your Export API key>
```

The entry point of the Export API. It lists the endpoints the API supports.

| Status | Body | Meaning |
|---|---|---|
| `200` | `{ "_links": ... }` | Links to the other endpoints this API supports |
| `403` | `{ "message": "..." }` | Forbidden. `message` says what went wrong. |

## Working with exports

- Dates are partitioned by **US Pacific** day. When you export on a schedule, overlap each export with the last one by a day, so nothing falls between them. For a weekly export every Monday, ask for the last 8 days: `startDate` the Sunday before last, `endDate` today.
- Overlapping exports return the same rows again. Load each day into your table by replacing that day's rows rather than appending, or remove the repeats after loading.
- A long-running conversation can appear as more than one row, one per time segment. See [Sessions and conversations](/data/sessions-and-conversations#long-running-threads).
- Dimensions exist only for conversations that have been enriched. History sent to `/trackhistorical` or uploaded as a file needs a [backfill](/dimensions/backfill) before it shows up in an export.
- To export one prompt's output, pass its name in `promptNames`, for example `support_ticket_info`. The **Prompts** tab lists every prompt. See [Custom Dimensions](/dimensions/custom).
- The Export API returns Dimensions. To keep your raw conversations, keep them in your own systems: they are already there, in the source you sent them from.

Rate limits are not published. Run exports one at a time, and retry a `429` or `5xx` with a growing pause.

Last reviewed on 2026-10-14.