historical download

Generates a pre-signed URL to download historical data (JSON) for a specific date.

GET/hist/{ticker}/{package}/{category}/{date}Quant Tier

Generates a pre-signed URL to download historical data (JSON) for a specific date.

Request

Example: /hist/SPX/state/gex_full/2025-11-14?noredirect

Headers

Name	Type	Description
`Authorization`	`string`	Required. Format: "Bearer <YOUR_API_KEY>"
`User-Agent`	`string`	Required. Identify your client application.
`Accept`	`string`	Required. Set to "application/json".

Path parameters

Name	Type	Description	Options
`ticker`	`string`	The ticker symbol (e.g., SPX, AAPL).
`package`	`string`	The data package to query.	`classic`, `state`, `orderflow`
`category`	`string`	The specific data category within the package.	`gex_full` (Classic, State), `gex_zero` (Classic, State), `gex_one` (Classic, State), `delta_zero` (State), `gamma_zero` (State), `vanna_zero` (State), `charm_zero` (State), `delta_one` (State), `gamma_one` (State), `vanna_one` (State), `charm_one` (State), `orderflow` (Orderflow)
`date`	`string`	The date to query in YYYY-MM-DD format.

The label after each category names the package that holds it. This endpoint needs a Quant API key for every package. The state package also accepts the three gex_* categories. The legacy names full, zero and one (classic) and delta, gamma, vanna, charm, onedelta, onegamma, onevanna and onecharm (state) are accepted and map to the canonical names. volume_zero and volume_one are not available on this endpoint (400).

Query parameters

Name	Type	Description
`noredirect`	`string`	Optional. If included (no value needed), returns a JSON object with the URL instead of a 302 redirect.

Response

Status	When	Body
`302 Found`	Default	Empty. The `Location` header holds the pre-signed URL.
`200 OK`	`?noredirect` present	`{"url": "..."}`

Field	Type	Description
`url`	`string`	A pre-signed URL allowing direct download of the historical file. Valid for 10 minutes.

{
  "url": "https://<storage-account>.blob.core.windows.net/gexbot-history/SPX/2025-11-14_SPX_state_gex_full.json.gz?sv=...&se=...&sr=b&sp=r&sig=..."
}

The URL points to Azure Blob Storage. The URL gives read access only. The URL expires 10 minutes after the request. Do not send your API key to that host.

{
  "type": "object",
  "required": ["url"],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "The temporary, pre-signed URL to download the requested historical data file. Valid for 10 minutes."
    }
  }
}

type: object
required:
  - url
properties:
  url:
    type: string
    format: uri
    description: The temporary, pre-signed URL to download the requested historical
      data file. Valid for 10 minutes.

Errors

Errors raised by the API have the body {"error": "<message>"}.

Status	Message	Cause
`400 Bad Request`	`User-Agent not found.`	The request has no `User-Agent` header.
`400 Bad Request`	`Authorization header not found.`	The request has no `Authorization` header.
`400 Bad Request`	`Invalid ticker format.` or `Unknown ticker symbol: <ticker>`	The ticker is not a supported symbol.
`400 Bad Request`	`Invalid package type.`	The package is not `classic`, `state` or `orderflow`.
`400 Bad Request`	`Invalid category type.` or `Invalid category package combination.`	The category does not exist, or it does not belong to the package.
`400 Bad Request`	`Invalid category`	The category is `volume_zero` or `volume_one`.
`400 Bad Request`	`Invalid start date format. Use YYYY-MM-DD.`	The date is not in `YYYY-MM-DD` format.
`401 Unauthorized`	—	The API key is not valid. The response carries no `{"error": ...}` body.
`403 Forbidden`	`User does not have permission to access this endpoint.`	The key belongs to a tier below Quant.
`403 Forbidden`	`User is not subscribed.`, `Classic package does not have access.` or `User is not subscribed to Orderflow package.`	The subscription does not include the package.
`403 Forbidden`	`Forbidden.`	The `User-Agent` value is `Google-Apps-Script`, `GoogleDocs` or `apps-spreadsheets`.
`404 Not Found`	`Data not found for date requested.`	No file exists for that date: a weekend, a holiday, a date before the evening export, or a date outside retention.
`429 Too Many Requests`	`Rate limit exceeded.`	The account exceeded its quota for this endpoint.

Notes & Data Handling

Download Guidelines

90-Day Retention: Historical snapshots are recorded at 1-second intervals during regular trading hours (~23,400 snapshots per session) for a rolling 90-day window.
Redirects & Direct URLs: By default, this endpoint returns a 302 Redirect to the storage file. To receive a JSON payload containing the signed download URL instead, include the ?noredirect query parameter (no value needed).
URL lifetime: Each signed URL expires 10 minutes after the request. Request a new URL if a download starts later.
Gzip Compression: The file is always gzip-compressed JSON (.json.gz). The blob is served with Content-Encoding: gzip and Content-Type: application/json. An HTTP client that decodes automatically (Python requests, browsers) receives plain JSON. curl needs --compressed or gunzip.
Quota: By default your account can make 2,000 requests per day and 40,000 per month on this endpoint (api_history_cache bucket, independent of other endpoints). All API keys of the account share this pool. Excess requests return 429 {"error": "Rate limit exceeded."}. Cache the signed URL or the file locally. Do not request the same file again.

Field Naming & Calculation Conventions

Expiry Prefixes:
- z_ / zero_ / un-prefixed: 0 DTE (Nearest Expiry).
- o_ / one_: 1 DTE (Next Expiry).
Cumulative vs. Point-in-Time:
- agg_* (agg_dex, agg_call_dex, agg_put_dex): Cumulative running sum since 09:30 ET session open. Resets daily.
- net_* (net_dex, net_call_dex, net_put_dex): Instantaneous snapshot of all open positions.
- *oflow (dexoflow, gexoflow, cvroflow): Instantaneous change per second.

historical download

On this page