Skip to main content

API conventions cheatsheet

This is the conventions cheatsheet — a single dense page summarising every protocol-level fact about the API that the rest of the guide assumes. If a later chapter says "standard parameter X," the definition is here.

Base URL and prefix​

Every endpoint sits under https://dev-datasets-api.algoseek.com/api/v1/ on the dev environment. The version is part of the path; bare /data/... is deprecated.

Authentication​

X-API-KEY: <opaque-key> request header on every call. Identity → IP allow-list → entitlement, in that order. 401 on identity failure, 403 on the other two; inspect body detail to disambiguate.

Standard query parameters (apply to every data endpoint)​

ParameterSemantics
limitMax rows per response. Default 1000, max 10000.
offsetRows to skip. Default 0.
sort`[+
columnsComma-separated projection: the list of columns to include.
response_formatjson (default), csv, csv_gzip.

Endpoint-specific flags​

adjusted=true on eq-trades*, eq-trades-1min*, eq-daily-ohlc routes to the corresponding adjusted dataset. aggregation_logic on eq-daily-ohlc accepts algoseek or industry_std and routes to that variant.

Column-name filters​

Any column on the dataset can be passed as a query parameter to filter rows by equality. Pascal case, exactly as it appears in the schema (Ticker=AAPL, not ticker=AAPL). The legal column set is per-dataset and discoverable via /api/v1/meta/datasets/{dataset_id}/columns (note: the opaque catalog dataset_id, a string of the form US#### — the human-readable dataset_text_id returns 404). Some endpoints require at least one filter (typically Ticker); others tolerate filterless calls.

Response shape (JSON)​

{
  "data": [ {"row1": "..."}, {"row2": "..."} ],
  "pagination": {
    "offset": 0,
    "limit": 1000,
    "next_offset": 1000
  }
}
  • offset — offset of the CURRENT page (echo)
  • next_offset — offset of the next page; null = terminal

Pagination signals​

JSON body's pagination object is the single authoritative source. Walk by issuing the next page at pagination.next_offset; stop when it comes back null. Do not follow the Link rel="next" header — it carries an internal origin URL over plain http:// and is unsafe; see pitfalls item 2 for the full account. The X-Pagination-Limit, X-Pagination-Next-Offset, and X-Pagination-Offset response headers are emitted on csv and csv_gzip responses but not on json; X-Pagination-Offset comes back empty-valued on page 1. The canonical pagination signal remains the body's pagination.next_offset.

Error envelope​

For every 4xx exercised in this guide (401, 403, 404, 422, 429), the body is {"detail": <string>} — a single human-readable string, not a list.

:::caution Gotcha This is a deliberate deviation from FastAPI's default 422 response shape ({"detail":[{"type","loc","msg","ctx"},...]}). The deployed Algoseek API flattens validation errors into a single detail string for every 4xx including 422. Clients written against "standard FastAPI" assumptions will fail to parse the response unless they handle the string variant. Treat the single-string form as canonical. :::

Status codes (summary)​

200 success ; 401 bad/missing key ; 403 IP not allowed OR dataset not entitled ; 404 unknown path ; 422 parameter validation failure ; 429 per-minute quota exceeded ; 5xx transient — retry with capped exponential backoff and jitter.

Quotas (summary)​

requests, data_scanned, data_returned each at per-month and per-minute horizons. Pooled at account level across keys. Per-month resets at 00:00 UTC on the 1st; per-minute is a rolling 60-second sliding window. The cap on the dev key is 10 requests / minute (quotas_limit.minute.requests). See quotas for the full explanation of the leaky-counter behaviour and the recommended 90 s recovery sleep.

Identity​

GET /api/v1/account/my returns the identity envelope. GET /api/v1/account/my/quotas returns current usage. GET /api/v1/account/my/data-access-rules returns the entitled datasets with date ranges and identifier universes.

Catalog​

GET /api/v1/meta/datasets (full catalog) / /my (entitled subset) / /{id}/info (one dataset's descriptor) / /{id}/columns (one dataset's column schema) / /{id}/status (publication status).

Two URL shapes for data endpoints​

Path-style, e.g. /data/us-equity/eq-trades/{trade_date}/{ticker}: trade date and ticker live in the URL path. Cannot be passed as query.

Query-style, e.g. /data/us-equity/eq-trades-1min: all filters (including the trade date and ticker) are query parameters using the column-name convention above.

Idempotency​

All data endpoints are GETs and are idempotent. Retry-on-transient-error is safe at any layer. No idempotency keys needed.

Content-Disposition​

On response_format=csv_gzip, the response carries a Content-Disposition: attachment; filename="..." header encoding the dataset variant, identifier, and date in a stable convention. Parse it for downstream partitioning rather than constructing the filename yourself.

Time zones​

Equity timestamps are in US/Eastern (EST/EDT depending on DST). Futures bar timestamps (BarDateTime) are in Chicago local time (CST in winter, CDT during DST); both are offset-tagged in the ISO-8601 string, so parse the offset rather than assuming a fixed hour shift. TradeDate fields are date-only and refer to the dataset's home market's calendar day.