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.
| Method | Path | Purpose |
|---|---|---|
POST | /datasets | Create a dataset + first upload session |
GET | /datasets | List your datasets |
GET | /datasets/{datasetId} | Get one |
DELETE | /datasets/{datasetId} | Delete |
POST | /datasets/{datasetId}/uploads | Open a new upload session for an existing dataset |
POST | /datasets/{datasetId}/uploads/{uploadId}/finalize | Trigger ingest |
GET | /datasets/{datasetId}/uploads/{uploadId} | Poll upload/ingest state |
POST | /datasets/imports | Create 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.
| Field | Type | Notes |
|---|---|---|
name | string | required, unique among your datasets. 409 if already taken |
instrument | string | required, 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:
| Form | Examples | Read as |
|---|---|---|
| ISO-8601 date | 2010-06-29 | midnight UTC, 2010-06-29T00:00:00Z |
| ISO-8601 date-time with a zone | 2010-06-29T14:30:00Z, 2010-06-29T14:30:00+02:00, 2010-06-29T14:30:00.123Z | that instant; an offset is honoured |
| ISO-8601 date-time with no zone | 2010-06-29T14:30:00, 2010-06-29T14:30 | that wall-clock time in UTC |
the same with a space instead of T | 2010-06-29 14:30:00 | that wall-clock time in UTC (or the zone, if it names one) |
| epoch seconds, milliseconds or microseconds | 1277821800, 1277821800000, 1277821800000000 | the 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 ingapsand is not an error. The version reportstimestampUnit: "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
| Field | Notes |
|---|---|
status | uploading (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) |
jobId | the ingest job id, while status is ingesting |
error | human-readable reason, present when status is failed. Durably recorded alongside the failure — stays available however long after the fact you poll |
version | a DatasetVersion, present when status is ready or failed |
DatasetVersion — one successfully ingested upload
| Field | Notes |
|---|---|
id | the version id — pass as datasetVersionId on prepare to pin it |
bytes | size 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 |
rows | number of data rows |
cadence | discovered 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 |
timestampUnit | iso | s | ms | us — the unit the timestamp column arrived in |
gaps, largestGapSteps | gap count at the discovered cadence, and the largest one’s size in cadence steps. Always 0 for rt |
dataUrl | presigned GET URL to the stored file — see dataFormat. Present once ready |
dataFormat | lastra (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
cadenceyou ask for, or at the plan’s default when you ask for none. The resulting dataset’stypeisklines, notticker(Whattypeis: candles carry no book), anddex.id/dex.versionare not needed. Swaps replayed as bars of a width, with no book either, come out asklinestoo. - 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
cadenceis omitted.
| Field | Type | Notes |
|---|---|---|
name | string | required, unique among your datasets. 409 if already taken |
instrument | string | required, plain spot pair — the dataset’s own label, independent of the pool’s on-chain token order |
from, to | string (date-time) | required, ISO-8601 UTC. from inclusive, to exclusive, from < to. Total span is capped by your tier |
cadence | string | optional, 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 |
type | string | required, "dex" | "cex" |
dex.network | string | required, one of ethereum | robinhood | solana. solana has candles only (see below) |
dex.id | string | required 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.version | string | required only for the per-trade import (no cadence, on a plan that includes the native rate); ignored when candles are built. "v2" | "v3" |
dex.contract | string | required, the pool (v3) or pair (v2) contract address |
dex.factory | string | optional — 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:
| Field | Type | Notes |
|---|---|---|
cex.exchange | string | required, the id of a centralized exchange (venueType cex) of GET /exchanges, lower-case. A decentralized exchange’s id is 400: use type: dex |
cex.segment | string | required, 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.dataType | string | required, "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
| Field | Notes |
|---|---|
status | fetching (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 |
jobId | the fetch/ingest job id, while status is fetching or ingesting |
error | human-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 |
version | a 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 rows | type |
|---|---|
carry an order book (bid, bidSize, ask or askSize) on any row | ticker |
have no book, and open, high, low and close on every row | klines |
anything else: only a close (a file of timestamp,close is a price), or only some of the four OHLC columns, or only some rows | ticker |
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 (
highequal tolow, 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.
| Field | Notes |
|---|---|
datasetId, name, type ("ticker" | "klines"), instrument, createdAt, status | always 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 |
currentVersionId | the most recently finalized, successfully ingested version. Absent until at least one upload has finished ingesting |
status | ready — 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) |
updatedAt | when currentVersionId last changed; absent until it has a value |
from, to, cadence, timestampUnit | the 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, largestGapSteps | the 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 |
error | why 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 run | dataset of type ticker | dataset of type klines |
|---|---|---|
ticker | yes | yes |
kline | 400 at prepare | yes |
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).