Sequential Docs
Sign in

Export your data

Owners and admins can export one project's events and sessions as NDJSON or CSV files, in the app or with an access token. See what the files hold, the limits and how long Sequential keeps them.

View as Markdown

On this page

Before you start

  • Your role. You must be an owner or admin of the organisation. Members and viewers also see the Export tab, but it shows only "Only owners and admins can export data."
  • A code, if you have 2FA. If your account has 2FA, Sequential asks for a code from your authenticator app, or a backup code, when you start an export. It does not ask if you entered a code in this sign-in in the last 15 minutes, for example when you signed in. A trusted device does not count. If you do not have 2FA, Sequential does not ask for a code.
  • Data that Sequential still keeps. An export holds only the days that Sequential still keeps under the organisation's events retention period. The range also cannot start before the day of the project's first event. The tab shows the period, for example "On this server that is the last 7 days." On Sequential's hosted service, the period is 7 days, unless Sequential support set a longer one for your organisation. See A server-wide limit.
  • A safe place for the files. The files hold personal data. Decide where you keep them before you download them.

Start an export

  1. Go to Settings → Projects → your project → Export.
  2. In From and To, set the first and the last day. The days are in UTC, and the export includes both days. At first, the form shows the oldest day that Sequential keeps and today.
  3. Contents shows Events, Sessions. Every export holds both. You cannot choose only one of them.
  4. Under Format, choose NDJSON, gzipped or CSV, gzipped. At first, NDJSON, gzipped is selected. See What an export holds.
  5. Read the warning: "Personal data. This file can hold emails, user ids and IP addresses as your app sent them. Treat it as personal data."
  6. Click Start export.
  7. If Sequential asks for a code, the dialog Confirm it is you opens. Enter the code from your authenticator app in Code, then click Confirm. To use a backup code, first click Use a backup code. The export then starts. You do not have to click Start export again.

The new export shows under Recent exports, with the status Waiting…. The export runs on the Sequential server, so you can close the page. While an export waits or runs, the page reads the list again every 5 seconds.

You cannot click Start export in two cases. Next to the button, the page says why:

  • "One export runs at a time." An export of this project shows Waiting… or Preparing….
  • "You can start 3 exports a day. Try again tomorrow." The list has 3 exports of this project that started today (UTC). Exports that failed count too.

Follow the export. Recent exports shows the exports of the project from the last 30 days, newest first. Each row shows the range, for example "8 Oct to 15 Oct 2026", the contents, the format and the status. A line under it says who started the export and when, for example "Started by Ana · 14:02 UTC". The line also gives the day when it is not today. An export that a token started shows "Started by an access token".

Status What it means What the row also shows
Waiting… The export waits for its turn. The exports of all projects on the server wait in one queue. "Starts next", or its place, for example "Number 3 in the queue on this server"
Preparing… Sequential reads the data and writes the files. "Reading the events" at first. Then the rows read so far, for example "Read 120,000 events and 0 sessions"
Ready The files are ready. See Download the files. The files, and "Files are deleted on 24 Oct 2026. Download makes a new link each time."
Failed The export stopped. It made no files. The reason, and Try again. See Messages
Expired Sequential deleted the files. "Files deleted on 24 Oct 2026."

On a failed export, Try again starts a new export with the same days and the same format. It counts toward the 3 exports of the day.

Download the files

  1. In Recent exports, find an export that shows Ready. It lists its files, each with its size, and manifest.json.
  2. Next to a file, click Download. Your browser downloads the file.
  3. Do step 2 for each file. Also download manifest.json. It lists the files with their row counts and their SHA-256 checksums.
  • Each click asks Sequential for a new link. A link works for up to 24 hours.
  • A download does not ask for a 2FA code.
  • Every owner and admin can download every export of the project. This includes the exports that another person or an access token started.
  • The sizes are in decimal units: 1 MB is 1,000,000 bytes.
  • The Audit log records each link as Export file downloaded. It never records the link itself.
  • Sequential keeps the files for 7 days after the export finishes. The line under the files gives the date, for example "Files are deleted on 24 Oct 2026."

What an export holds

One export is one project, one range of UTC days and one format. It always holds two sets of files and manifest.json:

File What it holds
events-0001.ndjson.gz, events-0002.ndjson.gz, … One row for each event whose time is in the range
sessions-0001.ndjson.gz, … One row for each session whose first event is in the range
manifest.json The export id, the project id, the format, the range and the time of the snapshot. For each file: its rows, its size, its SHA-256 checksum, and its first and last day

In CSV, the names end in .csv.gz.

  • Each data file is compressed with gzip. manifest.json is plain JSON. Its times are ISO 8601 in UTC, for example 2026-10-17T12:23:18.285Z.
  • Sequential starts a new file when the next part would take the file over 1,000,000 rows. It also starts a new file after a file reaches 256 MiB compressed.
  • Each CSV file starts with its own header line.
  • A set with no rows still has one file, so you always find both sets.
  • Times are in UTC. The range starts at 00:00 UTC on the From day and stops at the end of the To day (UTC).
Columns of the events files

The events files have these columns, in this order:

  • time_create, event_type, event_name, source, session_id, user_id, account_id, url
  • utm_referer, utm_source, utm_medium, utm_campaign, utm_term, utm_content
  • selector, platform_os, browser, country_code, user_ip, release
  • event_props_s, event_props_n, event_props_b, event_props_dt
  • visitor_props_s, visitor_props_n, visitor_props_b, visitor_props_dt
  • account_props_s, account_props_n, account_props_b, account_props_dt
  • ingested_at: the time when Sequential stored the event

The columns that end in _s, _n, _b and _dt hold the text, number, true or false, and date properties. The files have no project column: manifest.json names the project.

Columns of the sessions files

The sessions files have these columns, in this order:

  • session_id, first_time_create, last_time_create, event_count, user_count, first_event_type, last_event_type
  • user_id, account_id, source, event_name, platform_os, browser, country_code, user_ip, url, utm_referer
  • visitor_props_s, visitor_props_n, account_props_s, account_props_n

From user_id to account_props_n, each value is the latest value in the session.

What is not in an export

An export holds only events and sessions. It does not hold the Users and Accounts lists, findings, session recordings, heatmap data or AI judgments. The events and sessions files hold the user ids, the account ids and the properties that those lists show.

NDJSON or CSV

NDJSON, gzipped

  • Each line is one JSON object, for one row.
  • The values are as Sequential stores them. A time is text in UTC, with no T and no Z, for example 2026-10-08 14:02:11.123. ingested_at has whole seconds, for example 2026-10-08 14:02:12. A count is a number.
  • null and empty text stay different.
  • A property column is a list of name and value pairs, for example [{"name":"plan","value":"pro"}]. A column with no properties is [].

CSV, gzipped

  • The first line of each file is the header. The lines end with CR LF.
  • A time is ISO 8601 in UTC. time_create has milliseconds, for example 2026-10-08T14:02:11.123Z. ingested_at has whole seconds, for example 2026-10-08T14:02:12Z.
  • An empty cell is null or empty text. To tell them apart, use NDJSON.
  • A property column is one cell with a JSON object as text, for example {"plan":"pro"}. True or false properties are true or false. Date properties are ISO text.
  • A text cell that starts with =, +, -, @, a tab or a carriage return gets a ' in front of it. This stops a spreadsheet from running the cell as a formula. Number, time and property cells do not change. NDJSON files do not change.
Which sessions an export holds
  • A session is in the sessions files when its first event is in the range. A session that started before the From day is not in them, also when it has events in the range.
  • Sequential reads a session from the week of its first event and the next week. The weeks start on Monday (UTC). If a session goes on after that, its later events do not count in its row. For example, last_time_create, last_event_type and event_count do not include them. manifest.json states this rule too.
The events files are a snapshot

The events files hold the events that Sequential stored before the export started to run (Preparing…). Events that arrive later are not in them, also when their time is in the range. manifest.json gives this time as as_of. The sessions files have no such limit. They show the sessions as Sequential has them when it writes the files.

Limits

These are the default limits.

Limit Value What you see
Exports of one project in a day 3 a day (UTC), counted from 00:00 UTC. An export that failed counts. A request that Sequential refused does not count "You can start 3 exports a day. Try again tomorrow." The API answers 429 export_daily_limit
Exports of one project at a time 1 that waits or runs "One export runs at a time." The API answers 409 export_in_progress
Exports that wait on the server 20, for all projects together "Many exports are waiting on this server. Try again in 5 minutes." The API answers 503 export_queue_full
Estimated size of one export 10 GiB. Sequential counts 112 bytes for each event in the range, so the limit is about 95 million events "This range is too large to export. Pick a shorter range." The API answers 422 export_too_large
Files that one export writes 12 GiB compressed Failed, with "This range was too large to export. Pick a shorter range."
Time to make one export 4 hours Failed, with "The export took too long. Pick a shorter range."
Range UTC days, From and To included. To is today or earlier. At most 366 days. Only days that Sequential still keeps A message under From or To. The API answers 400 invalid_export_request or 422 range_before_retention
List and status reads 60 a minute, for each person or token, in each project The API answers 429 rate_limited
Download links 30 a minute, for each person or token, in each project "… could not be downloaded. Try again." The API answers 429 rate_limited
Requests with one access token 120 a minute, for all routes together The API answers 429 rate_limited
Files of an export Kept for 7 days after the export finishes Expired. The API answers 410 export_expired
One download link Works for up to 24 hours Ask for a new link

If Sequential cannot count a limit, it refuses the request and asks you to wait. It never lets the request through.

Use the API with an access token

A script can start an export, read its status and get the file links with an access token. The token needs the scope exports:write.

Create the token. Only an owner or admin can create it.

  1. Go to Settings → Projects → your project → Access tokens. Click Create an access token.
  2. Enter a Name. In Expires in, choose 30, 90 or 365 days.
  3. Under Access, choose Custom…. Tick Export this project's data and download the files (personal data). Its scope is exports:write.
  4. Click Create token.
  5. If Sequential asks for a code, Confirm it is you opens. It says "Enter a code from your authenticator app to create a token that can export data." Enter the code and click Confirm. Sequential then creates the token.
  6. Copy the token. The app says "This token is shown once. Copy it now, and treat it like a password."
  • Sequential asks for a code if your account has 2FA, and this sign-in did not pass a code in the last 15 minutes.
  • No preset includes exports:write. Choose it with Custom….
  • claude.ai and other agent connections never get exports:write.
  • If Custom… does not show the box, exports are not on for your Sequential server.
  • The token works only for its own project.
  • At each call, Sequential checks that the person who created the token is still an owner or admin of the organisation. If not, the call gets 403 export_creator_not_admin. Other owners and admins can still download the exports that the token started.
  • A call with the token needs no 2FA code.
  • The Audit log names the person who created the token. For an export that the token started, it also says "with an access token".

Call the API. Send the token in the header Authorization: Bearer sq_pat_…. In each path, <project id> is the id of the token's project. The project id is in the address of the project's settings, for example /settings/projects/<id>/export.

Method and path Body Answer
POST /api/projects/<project id>/exports {"from": "2026-10-01", "to": "2026-10-07", "format": "csv"}. All three fields are necessary. format is ndjson or csv 202 {"export": {…}}, with state queued
GET /api/projects/<project id>/exports None 200 {"exports": […]}: the exports of the last 30 days, newest first, at most 100
GET /api/projects/<project id>/exports/<export id> None 200 {"export": {…}}
GET /api/projects/<project id>/exports/<export id>/files/<file name> None 200 {"url": "…", "expires_at": "…"}. The file name is a name from files, or manifest.json

After the POST:

  1. Read the status until state is ready or failed. Wait some seconds between two reads. The limit is 60 reads a minute.
  2. For each file in files, and for manifest.json, ask for a link.
  3. Download each url before its expires_at. The link needs no token.

Each request for a link makes a new link and a new audit log entry.

The export object
Field What it holds
id The export id
state queued, running, ready, failed or expired
format, from, to The format, and the first and last UTC day
queue_position While queued: its place in the queue of the server. 1 is the next to run. Otherwise null
created_at, started_at, completed_at, expires_at ISO times in UTC, or null. expires_at is when Sequential deletes the files
files For each data file: name, table, rows and bytes. manifest.json is not in the list
rows events and sessions: null before the first part, the rows read so far while running, and the totals when ready
error When failed: export_too_large, export_read_budget, export_timeout, export_interrupted or export_failed. Otherwise null
requested_by {"kind": "member", "id": …} for a person, or {"kind": "token", "id": …} for a token
Replace each value in angle brackets, and put your token in TOKEN.
sh 
API="https://api.usesequential.com"
TOKEN="sq_pat_…"          # your access token
PROJECT="<project id>"

# 1. Start an export of 1 to 7 October 2026 (UTC), as CSV.
curl -s -X POST "$API/api/projects/$PROJECT/exports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-10-01","to":"2026-10-07","format":"csv"}'
# The answer holds the export id: {"export":{"id":"<export id>","state":"queued",…}}

# 2. Read the status. Do this again until "state" is "ready" or "failed".
curl -s "$API/api/projects/$PROJECT/exports/<export id>" \
  -H "Authorization: Bearer $TOKEN"

# 3. Ask for a link to one file. Do this for each file in "files", and for manifest.json.
curl -s "$API/api/projects/$PROJECT/exports/<export id>/files/events-0001.csv.gz" \
  -H "Authorization: Bearer $TOKEN"
# The answer: {"url":"<link>","expires_at":"<time>"}

# 4. Download the file from the link. The link needs no token.
curl -s -o events-0001.csv.gz "<link>"

Messages

In the app:

You see Cause What to do
"Only owners and admins can export data." Your role in the organisation is member or viewer. Ask an owner or admin to export the data.
"One export runs at a time." An export of this project shows Waiting… or Preparing…. Wait until it shows Ready or Failed.
"You can start 3 exports a day. Try again tomorrow." 3 exports of this project started today (UTC). Exports that failed count. Start the next export after 00:00 UTC.
"Many exports are waiting on this server. Try again in 5 minutes." 20 exports wait on the server. Wait for the time that the message gives. Then click Start export again.
"This range is too large to export. Pick a shorter range." The estimated size is more than 10 GiB. Choose fewer days. To get all the days, make two or more exports.
"Sequential no longer keeps data from before 10 Oct 2026." From is before the first day that Sequential keeps. Choose that day or a later day.
"Choose a day up to today (17 Oct 2026)." To is after today (UTC). Choose today or an earlier day.
"The To day is before the From day." To is before From. Change one of the days.
"Enter a day as YYYY-MM-DD." The day is not a real date. Enter the day again.
"The export could not be started. Try again." Sequential could not do one of its checks, for example the 2FA check or the size estimate. Wait a few seconds. Then click Start export again.
"The exports could not be loaded." Sequential could not read the list of exports. Click Try again.
"This range was too large to export. Pick a shorter range." The export failed: its files grew past 12 GiB compressed. Make two or more exports with shorter ranges.
"Sequential could not read this range within its limits. Pick a shorter range." The export failed: one part of the range needed more than the read limit of Sequential. Choose a shorter range.
"The export took too long. Pick a shorter range." The export failed after 4 hours. Choose a shorter range.
"The export stopped when the server restarted. Try again." The export stopped two times before it finished, for example because a server restarted. Click Try again.
"Sequential could not finish this export. Try again." The export failed for another reason. Click Try again.
"events-0001.csv.gz could not be downloaded. Try again." Sequential did not give a link. For example, the files were deleted, or you asked for more than 30 links in one minute. Wait one minute, then click Download again. If the files were deleted, reload the page: the export then shows Expired.

From the API, each refusal has a code in error:

Code Status Cause What to do
invalid_export_request 400 A field of the body is wrong. field names it. message says why, for example "to: on or before today (2026-10-17, UTC)" or "from: at most 366 days before to". Correct the field.
range_before_retention 422 from is before the first day that Sequential keeps. held_from gives that day. Send held_from or a later day as from.
export_too_large 422 The estimated size is more than 10 GiB. rows and projected_bytes give the estimate. Split the range into two or more exports.
export_in_progress 409 The project has an export that waits or runs. export_id names it. Wait until that export is ready or failed.
export_daily_limit 429 3 exports of this project started today (UTC). limit is 3. retry_after gives the seconds until 00:00 UTC. Wait until 00:00 UTC.
export_queue_full 503 20 exports wait on the server. retry_after is 300. Wait 5 minutes.
export_retention_unknown, export_precount_unavailable or TWO_FACTOR_CHECK_UNAVAILABLE 503 Sequential could not do a check: the first day that it keeps, the size estimate, or the 2FA check. Wait 5 seconds. Then send the request again.
TWO_FACTOR_STEP_UP_REQUIRED 403 A signed-in person with 2FA started an export, and this sign-in did not pass a code in the last 15 minutes. The message is "Enter a code from your authenticator (or a backup code) to export data". A token never gets this code. Enter a code in the app. Then try again.
export_not_ready 409 You asked for a link, but the export is not ready. state gives its state. Wait until state is ready.
export_expired 410 Sequential deleted the files. Start a new export.
not_found 404 The export id is unknown or belongs to another project, or the file is not in the export. A token also gets it for a project that is not its own. Check the ids and the file name.
rate_limited, with retry_after 429 More than 60 list and status reads, or more than 30 links, in one minute. Wait for retry_after seconds.
export_limit_unavailable 503 Sequential could not count the reads or the links. Wait for retry_after seconds.
rate_limited, with retry_after_sec 429 More than 120 requests with this token in one minute. The message is "Too many requests for this access token. Try again shortly." Wait for retry_after_sec seconds.
rate_limit_unavailable 503 Sequential could not count the requests of the token. Wait for retry_after_sec seconds.
invalid_token 401 "The access token is unknown, revoked or expired". Sequential also gives this code when the project is archived. Create a new token, or restore the project.
insufficient_scope 403 "This token lacks the exports:write scope" Create a token with exports:write.
export_creator_not_admin 403 "The person who created this token is no longer an owner or admin of this organization." Ask an owner or admin to create a new token.
export_check_unavailable 503 Sequential could not check the person who created the token. retry_after is 5. Wait 5 seconds.
forbidden 403 A signed-in member or viewer called the API. Ask an owner or admin.
export_disabled 404 Exports are not on for this Sequential server. Ask the team that runs the server.

Each answer that asks you to wait has the header Retry-After, in seconds. Some answers also give the seconds in the body: retry_after for the export limits and checks, and retry_after_sec for the limit of the token.

How long Sequential keeps exports

What How long Sequential keeps it
The files of an export 7 days after the export finishes. Then the export shows Expired, and Sequential gives no more links: the API answers 410 export_expired. Sequential deletes each file 7 to 8 days after it wrote the file
The files of a failed export Sequential deletes the parts that it wrote. It keeps no files
The record of an export: the range, the format, the status, who started it, the file names, the row counts and the sizes Until the project is deleted. The app and the API list only the exports of the last 30 days. The record holds no data from the files and no link
The files that you downloaded Sequential cannot delete your copies. Delete them when you no longer need them
  • Delete a project. Sequential deletes the export files of the project at once. If that fails, it tries again about every hour. The export records go with the project.
  • Delete an organisation. Sequential deletes the export files of its projects later, with a check that runs about every hour. The export records go with the organisation.

The Audit log records each step of an export:

Entry Recorded when
Export started Sequential accepts an export. The entry names the person, or the person who created the token, with the range and the format.
Export finished The files are ready. The entry gives the row counts, the number of files and the size.
Export failed The export stops before it finishes. The entry gives the reason when Sequential knows it.
Export file downloaded Someone asks for a link to a file. The entry names the file.