Datasets

Upload historical ticker data and use it in the standard backtesting workflow.

Backtest against a CSV, parquet, or lastra file you upload instead of a managed exchange: create a dataset, PUT the file to a presigned URL, finalize it to trigger ingest, then prepare/execute exactly as normal but with the reserved exchangeId: user.

MethodPathPurpose
POST/datasetsCreate a dataset + first upload session
GET/datasetsList your datasets
GET/datasets/{datasetId}Get one
DELETE/datasets/{datasetId}Delete
POST/datasets/{datasetId}/uploadsOpen a new upload session for an existing dataset
POST/datasets/{datasetId}/uploads/{uploadId}/finalizeTrigger ingest
GET/datasets/{datasetId}/uploads/{uploadId}Poll upload/ingest state
POST/datasets/importsCreate a dataset by fetching history instead of uploading it
GET/datasets/{datasetId}/imports/{importId}Poll fetch/ingest state

A dataset holds one instrument, and its type — ticker or klines — says what its rows are: it is read from the data when an upload or an import has been ingested, see What type is. instrument must be a plain spot pair (BASE/QUOTE, exactly one /); derivative forms (BTC/USDT:USDT) are rejected.

Creating a dataset

POST /datasets — creates the dataset and its first upload session in one call: a presigned URL your client PUTs the file to directly, no API credentials involved in that PUT.

FieldTypeNotes
namestringrequired, unique among your datasets. 409 if already taken
instrumentstringrequired, plain spot pair
curl -X POST https://api.qtsurfer.net/v1/datasets 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"name":"My BTC ticks","instrument":"BTC/USDT"}'

DatasetCreated (201) — the metadata available immediately after creation plus the upload session. It is not yet the full Dataset: lifecycle fields such as createdAt, currentVersionId, range, and cadence are obtained from GET /datasets/{datasetId} after the relevant lifecycle stages.

{
  "datasetId": "ds_3f9a1c2e7b0d4a5f", "name": "My BTC ticks",
  "type": "ticker", "instrument": "BTC/USDT",
  "uploadId": "up_1a2b3c4d5e6f7a8b",
  "upload": {
    "url": "https://storage.qtsurfer.com/.../uploads/up_1a2b3c4d5e6f7a8b/raw.csv?X-Amz-...",
    "expiresInMinutes": 15
  }
}

uploadId is what you pass to finalize; upload.url is the presigned target — PUT the raw file there directly, no Authorization header.

The "type": "ticker" of this response is provisional: the dataset has no data yet. Once the upload has been ingested its type is what the file holds (What type is), so a file of candles is klines when you read it back.

Lost this response? Nothing lost — call POST .../uploads on this dataset’s id and you get the very same upload session back, as long as you haven’t finalized it yet.

Errors: 400 invalid request, or instrument isn’t a plain spot pair · 409 dataset name already taken · 429 your tier’s dataset count limit is reached — delete one, or upgrade.

Opening a new upload session

POST /datasets/{datasetId}/uploads — get a fresh upload session for a dataset you already have: a corrected file, or the next chunk of history. Same idempotency contract as POST /datasets’s own upload half: at most one session is open per dataset at a time, so calling this again before finalizing just hands back that same session — safe to retry if a response gets lost. Once a session has been finalized (successfully or not), the next call here opens a genuinely new one.

curl -X POST https://api.qtsurfer.net/v1/datasets/$DATASET_ID/uploads 
  -H "Authorization: Bearer $TOKEN"

201 — the same {uploadId, upload} shape POST /datasets returns, without the dataset metadata around it:

{
  "uploadId": "up_1a2b3c4d5e6f7a8b",
  "upload": {
    "url": "https://storage.qtsurfer.com/.../uploads/up_1a2b3c4d5e6f7a8b/raw.csv?X-Amz-...",
    "expiresInMinutes": 15
  }
}

Errors: 404 no such dataset for this user.

Uploading the file

CSV, parquet, or lastra. A CSV needs a header row; a parquet file carries its columns by name already; a lastra file is our own native columnar format — the same one a dataset’s dataUrl hands you back by default, so downloading a dataset and handing that exact file to another user to upload works with no conversion in between. For CSV/parquet, timestamp (an ISO-8601 date or date-time, with no zone meaning UTC, or numeric epoch seconds / millis / micros — the forms are listed below) and close are required; optional: open, high, low, volume, quoteVolume, bid, bidSize, ask, askSize. A lastra upload carries its own fixed column set instead (it’s already a dataUrl download, not a format you construct by hand) and only needs a timestamp series and a close series present. Cadence and timestamp unit are discovered from the data, not declared, for all three.

A CSV upload is converted to our native columnar format (lastra) for storage. A parquet or lastra upload is stored as-is today. Either way, check dataFormat on the ready version for which one you actually get back — don’t assume it from how you uploaded it (a converted CSV and an uploaded lastra file both report dataFormat: "lastra").

The bytes PUT to upload.url may be that file directly, gzipped (.gz), or zipped (.zip, exactly one file inside — a dataset is one file regardless of how it travels). Format is detected from the content itself: there is no filename or Content-Type anywhere in this flow for a client to declare it with, so nothing needs to be sent besides the bytes.

curl -X PUT "$UPLOAD_URL" --data-binary @my-btc-ticks.csv
# or gzip/zip it first -- detected from content, no extra parameter needed
curl -X PUT "$UPLOAD_URL" --data-binary @my-btc-ticks.csv.gz

The timestamp column

The timestamp of a CSV reads in any of these forms:

FormExamplesRead as
ISO-8601 date2010-06-29midnight UTC, 2010-06-29T00:00:00Z
ISO-8601 date-time with a zone2010-06-29T14:30:00Z, 2010-06-29T14:30:00+02:00, 2010-06-29T14:30:00.123Zthat instant; an offset is honoured
ISO-8601 date-time with no zone2010-06-29T14:30:00, 2010-06-29T14:30that wall-clock time in UTC
the same with a space instead of T2010-06-29 14:30:00that wall-clock time in UTC (or the zone, if it names one)
epoch seconds, milliseconds or microseconds1277821800, 1277821800000, 1277821800000000the unit is read off the magnitude of the first row
  • No zone means UTC. A file exported in local time must carry the zone, or be converted, before it is uploaded: its rows are otherwise read as UTC.
  • The first row decides whether the column is ISO-8601 or epoch, and every later row must be of the same kind. Epoch rows must also stay in the unit the first row set; ISO-8601 rows may mix a date and a date-time.
  • Timestamps must strictly increase. Cadence and gaps are discovered as for any file: a daily series, dates alone, has cadence 1d, and a day with no row (a weekend, say) counts in gaps and is not an error. The version reports timestampUnit: "iso" for every ISO-8601 form.
  • Not accepted: day-first or month-first dates (29/06/2010, 06/29/2010) and month names, which are ambiguous. Rewrite such a column as ISO-8601 before uploading.

A timestamp in none of those forms fails the upload: status is failed and error names the line (line 1 is the header) and what would have been accepted:

line 2: not a valid timestamp: 29/06/2010. Accepted: an ISO-8601 date (2010-06-29, read as midnight UTC), an ISO-8601 date-time with or without a zone (2010-06-29T14:30:00Z, 2010-06-29 14:30:00; no zone means UTC), or epoch seconds, milliseconds or microseconds.

A later row that is not of the kind the first row set says so: Line 2 was read as ISO-8601, so every later line must be one too.

Finalizing an upload (triggering ingest)

POST /datasets/{datasetId}/uploads/{uploadId}/finalize — call once the PUT above completes. Enqueues ingest and returns immediately; poll GET .../uploads/{uploadId} below. Idempotent while the upload is still open — a repeat finalize before it has produced a version returns the same jobId rather than enqueueing a second ingest. Once it HAS produced a version, uploadId is spent: finalizing it again is a 409, even with different bytes freshly PUT to the same URL — open a new upload session instead of reusing a spent one.

curl -X POST https://api.qtsurfer.net/v1/datasets/$DATASET_ID/uploads/$UPLOAD_ID/finalize 
  -H "Authorization: Bearer $TOKEN"
# → 202 {"jobId": "dataset-upload:.../ds_3f9a1c2e7b0d4a5f:up_1a2b3c4d5e6f7a8b"}

Errors: 404 no such dataset for this user; uploadId wasn’t issued for this dataset (never minted, or minted for a different one); or nothing was PUT to upload.url yet — a finalize with nothing to finalize · 409 uploadId already produced a version (the error message names it) · 413 the uploaded file is many times your tier’s size limit for a dataset (see Size limits: the limit itself applies to the stored size, which is only known after conversion) · 429 your account’s total storage limit (GET /account’s maxTotalStorageBytes) is reached or would be exceeded — delete a dataset to free space, or upgrade.

Size limits

maxDatasetBytes (GET /account) caps a dataset version’s stored size: the bytes its ready version reports, which for a CSV upload is the converted lastra file, not the file you uploaded. Estimate from rows, not from the size of the file. The stored size follows the rows and the columns, and a CSV can come out larger or smaller than the file. Measured on synthetic one-second data: about 92 bytes per row for a timestamp,close CSV, about 55 for timestamp,open,high,low,close,volume. Real data compresses differently, so take these as an order of magnitude and, for a big file, upload a small slice first and scale from its bytes and rows.

The stored size is known only once the file has been converted, so that is where the limit decides: POST .../finalize answers 202, and an upload over the limit ends failed when you poll it, with an error such as Dataset is 196976000 bytes, exceeds the tier's 100000000 byte limit. Poll rather than assume the 202 means it stored. What finalize itself refuses with 413 is a file many times the limit, well beyond anything conversion could bring under it.

Polling ingest

GET /datasets/{datasetId}/uploads/{uploadId} — poll after finalize until status is ready or failed. Also reports uploading (finalize not called yet, but the file was PUT) before you finalize at all. Durably recorded once a version exists, so ready/failed are permanent answers; uploading/ingesting reflect in-flight state that can itself age out (see the 404 case below).

Response — DatasetUploadState

FieldNotes
statusuploading (file PUT, not finalized yet) → ingesting (finalize called, worker parsing/validating) → ready (version carries the result) | failed (e.g. bad CSV contract, a timestamp in none of the accepted forms, mixed timestamp units, a .zip with no file inside or more than one)
jobIdthe ingest job id, while status is ingesting
errorhuman-readable reason, present when status is failed. Durably recorded alongside the failure — stays available however long after the fact you poll
versiona DatasetVersion, present when status is ready or failed

DatasetVersion — one successfully ingested upload

FieldNotes
idthe version id — pass as datasetVersionId on prepare to pin it
bytessize of the stored file (dataUrl) — a converted lastra for a CSV upload (decompressed first, if it arrived as .gz/.zip), or the parquet/lastra file itself, unconverted, for a parquet or lastra upload. Not the size of the bytes originally PUT
rowsnumber of data rows
cadencediscovered from the data’s own timestamps: a fixed grid (1s, 5s, 15s, 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 1w) when at least half the intervals between rows fall on that step (small clock jitter tolerated), or rt — native data at the rate it was captured, each row at its own timestamp with no fixed step (per-trade on-chain swaps, block-spaced or sub-second ticks, irregular intervals). An rt dataset can be resampled to any fixed cadence at prepare time
timestampUnitiso | s | ms | us — the unit the timestamp column arrived in
gaps, largestGapStepsgap count at the discovered cadence, and the largest one’s size in cadence steps. Always 0 for rt
dataUrlpresigned GET URL to the stored file — see dataFormat. Present once ready
dataFormatlastra (either converted, from a CSV/gzip/zip upload, or unconverted, from a lastra upload — the value alone doesn’t tell you which) | parquet (unconverted, from a parquet upload)
curl https://api.qtsurfer.net/v1/datasets/$DATASET_ID/uploads/$UPLOAD_ID 
  -H "Authorization: Bearer $TOKEN"
{
  "uploadId": "up_1a2b3c4d5e6f7a8b",
  "status": "ready",
  "version": {
    "datasetId": "ds_3f9a1c2e7b0d4a5f", "id": "dsv_8e2b4f19c6a03d7e",
    "bytes": 4831022, "rows": 86400, "cadence": "1s",
    "timestampUnit": "iso", "gaps": 0, "largestGapSteps": 0,
    "dataUrl": "https://storage.qtsurfer.com/.../dsv_8e2b4f19c6a03d7e/ticker_BTC_USDT_....lastra?X-Amz-...",
    "dataFormat": "lastra"
  }
}

Errors: 404 no such dataset for this user, or genuinely nothing known about this uploadId — no version, no in-flight job, nothing was ever PUT to its upload URL.

Importing a dataset instead of uploading one

POST /datasets/imports — a second way to get data into a dataset: instead of PUTting a file yourself, ask the API to go fetch history on your behalf. Creates the dataset and starts the fetch in the same call — there’s no separate upload step, and the result lands as a dataset version indistinguishable from an uploaded one once it’s ready.

type selects the kind of venue the history comes from, with the same two values as the venueType of GET /exchanges: dex — history over a pool/pair’s own on-chain market — and cex — the history of a centralized exchange’s market, kept by the platform. Each has its own block (dex, cex). A decentralized exchange of GET /exchanges (robinhood, say) is imported with type: dex; as the exchange of a cex import its id is 400.

A cex import covers one instrument over a range: the API reads that range of the exchange’s history, builds the bars of the requested cadence from the finest data it has for it and stores the result as a dataset version, exactly as for an upload. See Importing an exchange’s history below.

An import is held to your plan’s cadences, the same ones as the preparation of an exchange’s data (Cadences by plan). A cadence your plan does not include is 402; a request that names none gets the plan’s default; any other cadence your plan includes can be asked for, and the 202 says the cadence the dataset is built at. An upload is not held to this: it is stored at the cadence detected in it, whatever that is, and is prepared at it whatever your plan.

A dex import has two data shapes:

  • Candles at the cadence you ask for, or at the plan’s default when you ask for none. The resulting dataset’s type is klines, not ticker (What type is: candles carry no book), and dex.id / dex.version are not needed. Swaps replayed as bars of a width, with no book either, come out as klines too.
  • On-chain swap history, replayed directly from the pool/pair’s own chain, each swap at its own timestamp (native per-trade cadence) — only on a plan that includes the native rate of a source, and when cadence is omitted.
FieldTypeNotes
namestringrequired, unique among your datasets. 409 if already taken
instrumentstringrequired, plain spot pair — the dataset’s own label, independent of the pool’s on-chain token order
from, tostring (date-time)required, ISO-8601 UTC. from inclusive, to exclusive, from < to. Total span is capped by your tier
cadencestringoptional, the same labels as a preparation (1s to 1q; any other value is 400); one your plan does not include is 402. For dex: candles at that width on a network that supports it; omitted/blank = the plan’s default, or native per-trade cadence on a plan that includes the native rate (see below). For cex: see Importing an exchange’s history
typestringrequired, "dex" | "cex"
dex.networkstringrequired, one of ethereum | robinhood | solana. solana has candles only (see below)
dex.idstringrequired only for the per-trade import (no cadence, on a plan that includes the native rate); ignored when candles are built. "uniswap" is the only value today — which on-chain DEX protocol dex.contract implements
dex.versionstringrequired only for the per-trade import (no cadence, on a plan that includes the native rate); ignored when candles are built. "v2" | "v3"
dex.contractstringrequired, the pool (v3) or pair (v2) contract address
dex.factorystringoptional — omit to auto-discover on-chain from contract; supply only if you already know it or the pool/pair belongs to a non-canonical factory. Either way the pool/pair is validated against whichever factory is used before anything is fetched. Ignored if a candle cadence actually resolves (see below)

On-chain cadence is native, not resampled. A plain dex import (no cadence) on a plan that includes the native rate of a source keeps the source’s own per-trade event cadence — each swap at the timestamp it happened, so the resulting version’s cadence is rt unless the swaps happen to sit on a fixed grid — rather than bucketing into candles; resample to a coarser cadence afterward as a separate step if you need one from on-chain data. Any other plan gets candles at its default instead, and so does an import that asks for a cadence: the bars are built at that width directly — but only on a network that actually has a candle source behind it. On any other network a plan that does not include per-trade data cannot be served and the request is 402; on a plan that does, the cadence is ignored and the import proceeds as if it were never sent (native, dex.id/dex.version required). Which networks support candles today isn’t part of this contract and may change.

Solana has candles only. There is no per-trade import for a Solana pool, so there is no native-rate case there: a request that names no cadence gets the plan’s default as candles on every plan, elite included (1s), and dex.id, dex.version and dex.factory are never needed. Any cadence your plan includes can be asked for, and one it does not is 402, as anywhere. The dex.contract of a Solana pool is its address in base58, which is case-sensitive: send it exactly as it is written.

Candles reach back 180 days. A candle import — one that names a cadence, or that gets the plan’s default — whose from is earlier than 180 days before the request is 400, whatever the network; the message says the earliest instant it can read. It is refused up front rather than accepted and failed later. The window does not apply to a per-trade import or to a cex import.

A width in which the pool had no trade may have no bar. Candles of a pool are not a contiguous grid: a second (or a minute) with no trade can be absent from the dataset, and that only means the price did not move and nothing traded. It is more common at 1s and on pools that trade rarely.

curl -X POST https://api.qtsurfer.net/v1/datasets/imports 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "weth-usdc-week",
    "instrument": "WETH/USDC",
    "from": "2026-08-01T00:00:00Z",
    "to": "2026-08-08T00:00:00Z",
    "type": "dex",
    "dex": {
      "network": "ethereum",
      "id": "uniswap",
      "version": "v3",
      "contract": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
    }
  }'
# → 202 {"datasetId":"ds_3f9a1c2e7b0d4a5f","importId":"imp_01j9z...","jobId":"dataset-import:...","status":"fetching"}

Or, for pre-aggregated candles instead of raw on-chain swaps:

curl -X POST https://api.qtsurfer.net/v1/datasets/imports 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "weth-usdc-1s",
    "instrument": "WETH/USDC",
    "from": "2026-10-27T00:00:00Z",
    "to": "2026-10-27T06:00:00Z",
    "cadence": "1s",
    "type": "dex",
    "dex": {
      "network": "ethereum",
      "contract": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
    }
  }'

The same for a Solana pool — candles only, the address as written:

curl -X POST https://api.qtsurfer.net/v1/datasets/imports 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "sol-usdc-5m",
    "instrument": "SOL/USDC",
    "from": "2026-10-27T00:00:00Z",
    "to": "2026-10-27T06:00:00Z",
    "cadence": "5m",
    "type": "dex",
    "dex": {
      "network": "solana",
      "contract": "Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE"
    }
  }'

importId is what you poll with, below — there’s no separate “finalize” step the way an upload has.

Errors: 400 invalid request, instrument isn’t a plain spot pair, from >= to, cadence present but not one of its supported values, a candle import whose from is earlier than the 180 days candles reach back, the range exceeds your tier’s import ceiling, the range’s rough size estimate exceeds your tier’s row limit, dex.network/dex.id not one of their supported values, dex.contract/dex.factory fail basic shape validation, or (when cadence is omitted on a plan that includes the native rate) dex.id/dex.version missing (whether the pool/pair actually resolves, and for a candle cadence whether that combination is servable on the requested network, is checked later, asynchronously — see failed below) · 402 cadence is not one of your plan’s, or per-trade data your plan does not include · 409 dataset name already taken · 429 your tier’s dataset count limit is reached, your account’s total storage limit (GET /account’s maxTotalStorageBytes) is already reached, or you already have as many imports in flight as your tier allows (maxConcurrentImports) — delete a dataset to free a slot or space, wait for an import to finish, or upgrade. An import is in flight from the moment it is accepted until it is ready or has failed; you do not have to poll it for its place to be freed.

Importing an exchange’s history

type: "cex" imports one instrument of a centralized exchange over a range. The same endpoint, the same name, instrument, from, to and cadence fields, the same poll below and the same limits, except the range: it is capped by your tier’s maxCexImportRangeHours (GET /account), in hours and apart from a pool’s maxImportRangeHours. The history is already kept by the platform, so on the larger plans the range reaches weeks; what bounds it is how much you then load, a bar a second being about 57 bytes in the stored file and 88 in memory. Only the block that says what to import changes:

FieldTypeNotes
cex.exchangestringrequired, the id of a centralized exchange (venueType cex) of GET /exchanges, lower-case. A decentralized exchange’s id is 400: use type: dex
cex.segmentstringrequired, one of the exchange’s segments. spot is the only segment a cex import takes today, which matches instrument being a plain spot pair
cex.dataTypestringrequired, "ticker" | "klines". What is fetched, and so the resulting dataset’s type (What type is: the tickers carry the book, the klines do not)

cadence is optional, and takes the same labels as the cadence of a backtest preparation, for tickers and for klines alike: 1s, 5s, 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 1w or 1q. Any other label is 400, and one your plan does not include is 402. Omitted, the dataset gets the plan’s default; a plan that includes the native rate of a source gets the finest cadence every part of the range holds instead. The bars are built from the finest data every part of the range holds, so, when the range decides, a range whose history changes cadence part-way (from 1m to 1s, say) comes out entirely at the coarser one: the dataset has no gap that is only a change of cadence. A cadence finer than that, or not an exact multiple of it, fails the import (failed, and error names the finest cadence the range holds) instead of giving you a dataset with a different cadence from the one you asked for.

curl -X POST https://api.qtsurfer.net/v1/datasets/imports 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "btc-usdt-1s-sept",
    "instrument": "BTC/USDT",
    "from": "2026-09-01T00:00:00Z",
    "to": "2026-09-01T06:00:00Z",
    "cadence": "1s",
    "type": "cex",
    "cex": {
      "exchange": "binance",
      "segment": "spot",
      "dataType": "klines"
    }
  }'
# → 202 {"datasetId":"ds_3f9a1c2e7b0d4a5f","importId":"imp_01j9z...","jobId":"dataset-import:...","status":"fetching"}

Errors, in addition to the ones above: 400 no cex block, cex.exchange not a centralized exchange of GET /exchanges (a decentralized one included), cex.segment not spot, cex.dataType not ticker or klines, or a cadence that is none of the labels above. Whether the range holds data, and whether it holds data fine enough for the cadence, is checked later, asynchronously: see failed below.

Polling an import

GET /datasets/{datasetId}/imports/{importId} — poll after POST /datasets/imports until status is ready or failed. An import spends real time fetching from its source before anything is even staged; once fetched, it re-enters the exact same ingest chain an upload uses.

Response — DatasetImportState

FieldNotes
statusfetching (reading from the source, nothing staged yet — the one status only an import ever reports) → ingesting (fetched, staged, worker parsing/validating) → ready (version carries the result) | failed
jobIdthe fetch/ingest job id, while status is fetching or ingesting
errorhuman-readable reason, present when status is failed — an unresolvable pool/pair, no data in the requested range, a range older than the source retains, a cex cadence finer than the range holds (the message names the finest one), the fetch exceeding your tier’s time ceiling, or any of the ingest-side reasons DatasetUploadState.error can carry, once fetching hands off to that same chain. Durably recorded, same as on the upload path
versiona DatasetVersion, present when status is ready or failed
curl https://api.qtsurfer.net/v1/datasets/$DATASET_ID/imports/$IMPORT_ID 
  -H "Authorization: Bearer $TOKEN"
{
  "importId": "imp_01j9z1x2y3z4a5b6c7d8e9f0g1",
  "status": "ready",
  "version": {
    "datasetId": "ds_3f9a1c2e7b0d4a5f", "id": "dsv_8e2b4f19c6a03d7e",
    "bytes": 4831022, "rows": 604800, "cadence": "rt",
    "timestampUnit": "us", "gaps": 0, "largestGapSteps": 0,
    "dataUrl": "https://storage.qtsurfer.com/.../dsv_8e2b4f19c6a03d7e/ticker_WETH_USDC_....lastra?X-Amz-...",
    "dataFormat": "lastra"
  }
}

Errors: 404 no such dataset for this user, or genuinely nothing known about this importId.

What type is

A dataset’s type says what its rows are. It is decided when a version becomes ready, and it is the type of the current version. An import that already knows what it fetched says so, and nothing is guessed: a cex import is its dataType, and a dex import that asked for candles is klines. Everything else (a CSV, Lastra or Parquet upload, a dex import of on-chain swaps) is read from the rows:

The rowstype
carry an order book (bid, bidSize, ask or askSize) on any rowticker
have no book, and open, high, low and close on every rowklines
anything else: only a close (a file of timestamp,close is a price), or only some of the four OHLC columns, or only some rowsticker

Two more checks keep a ticker from passing for candles. In a ticker the open, high, low and volume are the exchange’s rolling 24-hour figures, not those of an interval. A file with no book stays ticker if either holds:

  • The high and low hardly ever change. At least 100 rows in which they change between fewer than 1 in 200 consecutive rows. A file where every row has the same price (high equal to low, an instrument nobody traded) is still candles. This check cannot tell 24-hour figures from bars at a coarse cadence (an hour or more).
  • The opens do not follow the closes. A bar opens where the previous one closed (within 0.01 % of it); the open of a 24-hour window does not. At least 20 rows of which fewer than 1 in 20 open at the close before them.

Only the rows of an upload and of a dex import of swaps go through these checks. They decide nothing for an import that declares its type.

Until the first version is ready the type is only the label of the way the dataset was created (ticker for an upload, klines for an import that asked for candles). A later upload of another kind of data changes the dataset’s type; each version keeps its own, and a backtest that pins datasetVersionId is judged by that version’s. Datasets stored before this rule keep the type they had.

Dataset shape

Both GET /datasets and GET /datasets/{datasetId} return this — from/to/cadence/timestampUnit mirror the current version’s own discovered range, cadence and timestamp unit, and status, bytes, rows, gaps and largestGapSteps say whether it is usable and how big it is, so you don’t need a second call to see what a dataset covers.

FieldNotes
datasetId, name, type ("ticker" | "klines"), instrument, createdAt, statusalways present. type says what the rows of the current version are, decided when the version became ready (What type is): "klines" for candles (an upload with open, high, low and close on every row and no book; a dex import that requested a candle cadence; a cex import with dataType: "klines"), "ticker" for a book or a bare price. Before the first version is ready it is only the label of the way the dataset was created
currentVersionIdthe most recently finalized, successfully ingested version. Absent until at least one upload has finished ingesting
statusready — currentVersionId is set and the fields below describe it; failed — the most recent upload or import attempt failed, there is nothing to read yet (see error); pending — nothing has ever been attempted (just created, or an upload was never finalized)
updatedAtwhen currentVersionId last changed; absent until it has a value
from, to, cadence, timestampUnitthe current version’s own range/cadence/timestamp unit (a fixed grid or rt cadence, iso|s|ms|us for timestampUnit, see DatasetVersion), as discovered at ingest. Absent until a version exists
bytes, rows, gaps, largestGapStepsthe current version’s own stored size, row count, gap count and largest gap (in steps of its cadence). Present only when status is ready — see DatasetVersion for what bytes measures
errorwhy the most recent attempt failed. Present only when status is failed

GET /datasets/{datasetId} alone adds dataUrl/dataFormat (same meaning as on DatasetVersion) once the current version is ready, plus _links.self. The bulk listing never mints these — a presigned download URL for every dataset on a screen that renders no chart isn’t worth the exposure.

Listing your datasets

GET /datasets — every dataset you’ve created and not deleted, most recently created first. Never a 404 — an empty array if you have none, same convention as GET /strategies.

curl https://api.qtsurfer.net/v1/datasets -H "Authorization: Bearer $TOKEN"

GET /datasets?includeDeleted=true also lists the datasets you’ve deleted, each with the deletedAt it was deleted at — handy when keeping your own copy of the list in sync, so a deleted dataset shows up as deleted instead of just disappearing.

Getting a dataset

GET /datasets/{datasetId} — a Dataset plus a _links.self.

curl https://api.qtsurfer.net/v1/datasets/$DATASET_ID -H "Authorization: Bearer $TOKEN"

Errors: 404 no such dataset for this user.

Deleting a dataset

DELETE /datasets/{datasetId} — soft delete. Stops appearing in the list/get endpoints and can no longer be prepared from, but its object data is reclaimed later rather than purged inline, so a backtest already running against one of its versions isn’t disrupted.

curl -X DELETE https://api.qtsurfer.net/v1/datasets/$DATASET_ID -H "Authorization: Bearer $TOKEN"
# → {"datasetId": "ds_3f9a1c2e7b0d4a5f", "deleted": true}

Errors: 404 no such dataset for this user, or already deleted.

Backtesting against a dataset

Once a version is ready, prepare and execute exactly as against a managed exchange, but with exchangeId: user and datasetId in place of instrument:

curl -X POST https://api.qtsurfer.net/v1/backtest/user/ticker/prepare 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"datasetId":"ds_3f9a1c2e7b0d4a5f","from":"2026-03-14","to":"2026-03-15"}'
# → 202 {"jobId":"5ikYAMIO...","datasetId":"ds_3f9a1c2e7b0d4a5f","datasetVersionId":"dsv_8e2b4f19c6a03d7e"}

execute is unchanged — same request body as against a managed exchange, since the instrument and range are recovered from prepareJobId either way. See docs/backtest_execute.md for the full prepare/execute reference, including PrepareRequest’s datasetId/datasetVersionId fields and the dataset-backed coverage shape on PrepareJobState (cadence/gaps/largestGapSteps in place of the hour-walked totalHours/hoursWithData/hoursWithoutData).

Which datasets run under which {type}

The {type} in the path says what the strategy is fed; the dataset’s own type says what it holds. Both ticker and kline runs take a dataset, and a dataset of candles can be run either way:

{type} of the rundataset of type tickerdataset of type klines
tickeryesyes
kline400 at prepareyes

A kline run over a dataset reads the dataset’s own rows as the bars: no ticker is built from them. By default each row is one bar, at the dataset’s own cadence. A coarser cadence that is an exact multiple of it aggregates the rows into wider bars, and a bar the range covers only partly is dropped rather than emitted short. execute, executeSweep and walk-forward all take it.

The bar a row belongs to is its timestamp floored to the dataset’s cadence, so a file stamped at the open of each bar and one stamped at its close (the last millisecond of the bar) give the same bars. A timestamp that sits off the grid of the cadence (a one-minute file stamped at :20 of each minute) is floored onto it, and the first bar, which then opens before your from, is dropped like any bar the range covers only partly.

A kline prepare over a dataset that is not klines is refused with a 400 that names the dataset’s type, before anything is queued, and says to prepare it as ticker data instead. A ticker run over a klines dataset is accepted: each bar is read as one sample, with no order book.

The type this table reads is the one of the version the run will read: the current version, or the one a datasetVersionId pins (What type is). A file you upload is therefore klines once ingested if it holds candles (open, high, low and close on every row, each open at the close before it, no book), and runs as bars; a file with a book, or only a price, is ticker. A dataset of candles also comes from an import of an exchange’s candles (or a dex import that asks for a candle cadence).