Using the API

Exports

For a long range (a full day of footprint, months of data for a backtest), an export replaces pagination: one request, and results stream in as they are computed.

Exports come with the Historical plan and require a key with the export scope.

When to use an export

You needUse
A few thousand results, for displayA history query
A full day or more, a backtest, a databaseAn export (one per contract if the range crosses a rollover: with NQ.front, the whole export reads the contract designated at from)
Load the past, then follow the marketfrom: {"time": …} on the WebSocket

Start an export

The body is the same as a history query, without limit, cursor, untilCursor or snapshot. mode works the same way: "mode": "confirmed" keeps only the final versions, and from and to bound the time our servers received the trades, as in history. Here, to keep the example cheap, 25 minutes of footprint from the US cash open (13:30 to 13:55 UTC on September 24, 2026), which cost 46,811 compute units.

An export is charged for its whole range as soon as it starts. A full UTC day of footprint on NQ (September 24, 2026, for example) costs about 457,000 compute units, a month around ten million. Estimate the range first, for free, with the same body.

BASH
curl -sS --fail-with-body https://api.fathomcharts.com/v1/exports \
  -H "Authorization: Bearer $FATHOM_CHARTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instrument":"NQZ6","indicator":"footprint","params":{"timeframe":60,"groupTicks":4},"from":"1790256600000000000","to":"1790258100000000000"}' \
  -o footprint-NQZ6-2026-09-24.ndjson.zst && zstd -d footprint-NQZ6-2026-09-24.ndjson.zst

The response is a zstd-compressed NDJSON file, whatever the Accept-Encoding header of the request: Content-Type: application/zstd, without Content-Encoding, so neither curl nor fetch decompresses it. zstd -d writes the decompressed file next to it, footprint-NQZ6-2026-09-24.ndjson. With --fail-with-body (curl 7.76 or later), a 4xx or 5xx error stops the command before zstd: its problem+json document is then in the .zst file, in plain text. The response also carries a Content-Disposition header with a suggested file name (<indicator>-<contract>-<from>-<to>.ndjson.zst, <from> and <to> in nanoseconds) and the X-Export-Token header, used to resume the export.

The zstd tool is not installed by default on macOS or Windows: brew install zstd on macOS; on Windows, winget install Meta.Zstandard, then reopen the terminal. On Linux, it is in your distribution’s zstd package.

The curl examples on this page are written for bash (macOS, Linux, Git Bash on Windows). In PowerShell, write curl.exe, send the body from a file with -d "@export.json", as in the Quickstart, and run zstd -d as a separate command: Windows PowerShell 5.1 strips the quotes of a JSON argument passed to a program (the API then responds with 400 INVALID_PARAMETERS, The body is not valid JSON) and does not accept &&.

What is charged

  • Compute units: the cost of the whole range, the one the estimate gives, is charged as soon as the export starts, even if you stop reading the response before the end. A resume within 24 hours (the token’s validity) costs no compute units.
  • Export volume: the downloaded bytes, compressed, count against your monthly export volume at the end of every response, resumes included.

A new export is rejected before it starts, with 429 QUOTA_EXCEEDED, if its cost exceeds what is left of your compute budget or if your export volume is used up. A resume is only rejected when your export volume is used up. An export started while you have volume left runs to the end, even if it exceeds what was left: the volume is charged at the end, and the next export is rejected.

File format

One JSON line per update, in order, in the same shape as a history query result. For example, the 13:33 UTC bar at its close:

JSON
{"cursor":"20720.124235.0","t":"upsert","id":"1790256780000000000","final":true,"ts":"1790256840033077853","data":{"open":122026,"high":122133,"low":122009,"close":122103,"levels":[[122008,14,3],[122012,44,31],[122016,31,37],[122020,16,32],[122024,48,24],[122028,26,24],[122032,40,28],[122036,24,75],[122040,35,46],[122044,14,32],[122048,12,14],[122052,12,9],[122056,20,9],[122060,36,38],[122064,61,58],[122068,29,68],[122072,28,37],[122076,19,20],[122080,30,46],[122084,32,29],[122088,39,42],[122092,87,67],[122096,154,125],[122100,151,163],[122104,149,192],[122108,66,99],[122112,50,81],[122116,22,38],[122120,27,42],[122124,39,72],[122128,10,25],[122132,0,8]],"poc":122104}}

Footprint only sends completed bars: each bar appears once in the file. With an indicator that publishes in-progress objects (big-trades, for example), the file also contains, as history does in live mode (the default), the intermediate versions (final: false). If you only care about the finished result, request the export with "mode": "confirmed", or filter on final: true.

A complete response ends with exactly one end line, after the last update:

JSON
{"t":"end"}

A response without this line was interrupted: resume it. Each response of a resume also ends with its own end line: when you concatenate the responses, drop each end line (or keep only the last one).

Lines arrive as soon as they are computed. Process them as they come rather than loading the whole file into memory.

With the SDK

rest.exportNdjson()rest.export_ndjson()rest.ExportNdjsonAsync()rest.export_ndjson() decompresses, splits into lines and, if the connection drops or the end line is missing, resumes automatically after the last line received. It only hands you the update lines, never the end line, in chunks of whole lines:

src/export.ts
import { createWriteStream } from 'node:fs';
import { FathomChartsRest } from '@fathom-charts/sdk';

const rest = new FathomChartsRest({ baseUrl: 'https://api.fathomcharts.com', apiKey: process.env.FATHOM_CHARTS_API_KEY! });
const out = createWriteStream('footprint-NQZ6-2026-09-24.ndjson');

for await (const lines of rest.exportNdjson({
  instrument: 'NQZ6',
  indicator: 'footprint',
  params: { timeframe: 60, groupTicks: 4 },
  from: '1790256600000000000',
  to: '1790258100000000000',
})) {
  if (!out.write(lines)) await new Promise<void>((r) => out.once('drain', () => r()));
}
out.end();
export.py
import asyncio
import os
from contextlib import aclosing

from fathom_charts import FathomChartsRest


async def main() -> None:
    async with FathomChartsRest(base_url="https://api.fathomcharts.com", api_key=os.environ["FATHOM_CHARTS_API_KEY"]) as rest:
        with open("footprint-NQZ6-2026-09-24.ndjson", "wb") as file:
            async with aclosing(rest.export_ndjson({
                "instrument": "NQZ6",
                "indicator": "footprint",
                "params": {"timeframe": 60, "groupTicks": 4},
                "from": "1790256600000000000",
                "to": "1790258100000000000",
            })) as chunks:
                async for lines in chunks:
                    file.write(lines)


asyncio.run(main())
Program.cs
using FathomCharts;
using FathomCharts.Indicators;

using var rest = new FathomChartsRest(new RestOptions
{
    BaseUrl = "https://api.fathomcharts.com",
    ApiKey = Environment.GetEnvironmentVariable("FATHOM_CHARTS_API_KEY"),
});

using var file = File.Create("footprint-NQZ6-2026-09-24.ndjson");
await foreach (var chunk in rest.ExportNdjsonAsync(new RangeQuery
{
    Instrument = "NQZ6",
    Indicator = IndicatorIds.Footprint,
    Params = new FootprintParams { Timeframe = 60, GroupTicks = 4 },
    From = "1790256600000000000",
    To = "1790258100000000000",
}))
{
    await file.WriteAsync(chunk, 0, chunk.Length);
}
src/main.rs
use fathom_charts::{ExportOptions, FathomChartsRest, RangeQuery};
use futures::StreamExt;
use serde_json::json;
use tokio::io::AsyncWriteExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let rest = FathomChartsRest::new(
        "https://api.fathomcharts.com",
        std::env::var("FATHOM_CHARTS_API_KEY").map_err(|_| "FATHOM_CHARTS_API_KEY is not set")?,
    )?;

    let query = RangeQuery::new("NQZ6", "footprint", "1790256600000000000", "1790258100000000000")
        .params(json!({ "timeframe": 60, "groupTicks": 4 }));

    let mut file = tokio::fs::File::create("footprint-NQZ6-2026-09-24.ndjson").await?;
    let mut lines = Box::pin(rest.export_ndjson(query, ExportOptions::default()));
    while let Some(chunk) = lines.next().await {
        file.write_all(&chunk?).await?;
    }
    file.flush().await?;
    Ok(())
}

The very first request can fail with a network error or a 5xx before the X-Export-Token header. The SDK does not send it again, since a new export would be charged again: it throws the error, and you decide. The option maxResumesmax_resumesMaxResumesmax_resumes bounds the number of consecutive resumes without a new line, 5 by default. In C# and Rust, it is set in ExportOptions. In TypeScript, decompression requires Node 22.15 or later; elsewhere, exportNdjson() throws CONFIGURATION.

To save the compressed file as is, without automatic resume, use rest.export()rest.export()rest.ExportAsync()rest.export(): it returns the zstd file as sent, its type, the suggested file name and the resume token. In a browser, decompress the file with a zstd library.

Without the SDK, in Node

createZstdDecompress requires Node 22.15 or later. The program stops at the end line, and treats its absence (or a truncated last line) as an interruption. It uses top-level await: save it as export.mts (or in a project with "type": "module"), then run it with npx -y tsx export.mts.

TS
import type { IncomingMessage } from 'node:http';
import { request } from 'node:https';
import { pipeline } from 'node:stream';
import { createZstdDecompress } from 'node:zlib';
import { createInterface } from 'node:readline';

const body = JSON.stringify({
  instrument: 'NQZ6',
  indicator: 'footprint',
  params: { timeframe: 60, groupTicks: 4 },
  from: '1790256600000000000',
  to: '1790258100000000000',
});

// The response, or the connection failure: a promise rather than an error thrown inside an event handler.
const res = await new Promise<IncomingMessage>((resolve, reject) => {
  const req = request('https://api.fathomcharts.com/v1/exports', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.FATHOM_CHARTS_API_KEY}`,
      'Content-Type': 'application/json',
    },
  }, resolve);
  req.on('error', reject);
  req.end(body);
});

if (res.statusCode !== 200) {
  // Errors are application/problem+json, not compressed.
  let problem = '';
  for await (const chunk of res) problem += chunk;
  throw new Error(problem);
}

// Keep it to resume the export after a disconnect (see below).
const exportToken = res.headers['x-export-token'];

type Line = { t: 'upsert' | 'remove' | 'end'; cursor: string; id: string; final: boolean };
let after: string | undefined; // cursor of the last complete line
let ended = false;

// pipeline passes an interrupted connection (an error on res) on to the decompression, and so to the read loop.
const unzstd = createZstdDecompress();
pipeline(res, unzstd, () => {});
const lines = createInterface({ input: unzstd, crlfDelay: Infinity });
try {
  for await (const line of lines) {
    let m: Line;
    try {
      m = JSON.parse(line);
    } catch {
      break; // a truncated last line: the export was interrupted
    }
    if (m.t === 'end') {
      ended = true; // the end line: the response is complete
      break;
    }
    after = m.cursor;
    if (m.t === 'upsert' && m.final) console.log(m.cursor, m.id);
  }
} catch {
  // a read error (network drop): handled below as a missing end line
}

// No end line: the export was interrupted. Resume it after the last complete line.
if (!ended) throw new Error(`Export interrupted after ${after}: resume with token ${exportToken}`);

Resume after a disconnect

A long export can be interrupted (network drop, maintenance): you see a read error, or the end line {"t":"end"} is missing from the decompressed file. No need to start over:

  1. keep the X-Export-Token header of the response (valid for 24 hours);
  2. note the cursor of the last complete line you received, and ignore any truncated line at the end. A cursor whose UTC day is outside the range of the export cannot come from it: it is rejected with 400 INVALID_PARAMETERS (path /resume/after);
  3. send exactly the same request again, adding resume:
JSON
{
  "instrument": "NQZ6",
  "indicator": "footprint",
  "params": { "timeframe": 60, "groupTicks": 4 },
  "from": "1790256600000000000",
  "to": "1790258100000000000",
  "resume": { "token": "<value of X-Export-Token>", "after": "20720.124235.0" }
}

The export picks up right after that line. If no complete line was received (on a small export, the whole file can fit in a single compressed block), send resume with the token alone, without after: the export starts over from the beginning, with no new compute charge. The new response is a new compressed file, which ends with its own end line: decompress each response separately, then concatenate the lines, dropping the intermediate end lines. The result is identical to an uninterrupted export. A resume within 24 hours costs no compute units; only the downloaded bytes count against your export volume.

If we have updated how the indicator is computed since the export started, the resume is refused with 410 CURSOR_EXPIRED: the remaining lines would be computed differently from the ones you have. Start the export again, without resume, and drop the lines already received (see Updates and maintenance).