TradePolaris Data API

Make your first request

Search for a dataset first, inspect its schema, and only then choose filters. This avoids guessing slugs, columns, date fields, or point-in-time support.

1. 1
   Create a key

   Approved accounts create keys in the authenticated Data API console. Store the show-once secret in a secrets manager.

2. 2
   Search, then inspect

   Resolve a dataset with GET /datasets?q=…, then read /schema before querying rows.

3. 3
   Query or export

   Use bounded JSON for applications, complete-or-rejected CSV for filtered extracts, or checksummed Parquet for a full immutable version.

export TP_API_KEY="tp_live_..."

curl --fail-with-body \
  --header "Authorization: Bearer $TP_API_KEY" \
  "https://api.tradepolaris.com/platform/v1/datasets?q=apple&limit=10"

import hashlib
import os
import requests

BASE_URL = "https://api.tradepolaris.com/platform/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['TP_API_KEY']}"

# Search first; do not page the full catalog.
catalog = session.get(
    f"{BASE_URL}/datasets",
    params={"q": "apple", "limit": 10},
)
catalog.raise_for_status()
dataset = catalog.json()[0]["name"]

# Inspect capabilities before choosing filters.
schema_response = session.get(f"{BASE_URL}/datasets/{dataset}/schema")
schema_response.raise_for_status()
schema = schema_response.json()

# JSON rows are paginated and DataFrame-ready.
rows_response = session.get(
    f"{BASE_URL}/datasets/{dataset}/query",
    params={"start": "2026-01-01", "limit": 5000},
)
rows_response.raise_for_status()
page = rows_response.json()
print(page["columns"], page["rows"], page["truncated"])

# For the immutable full version, verify the exported Parquet bytes.
export_response = session.get(f"{BASE_URL}/datasets/{dataset}/export")
export_response.raise_for_status()
artifact = export_response.json()
download = requests.get(artifact["url"])  # no API Authorization header
download.raise_for_status()
expected_sha256 = artifact.get("content_sha256")
if not expected_sha256:
    raise RuntimeError("Export did not include a checksum")
assert hashlib.sha256(download.content).hexdigest() == expected_sha256

Authentication and scopes

Send the key on every request. The secret begins with tp_live_, is shown once, and cannot be retrieved later.

Authorization: Bearer tp_live_...

• Keys expire after 1–365 days; the default is 90 days.
• Up to five keys can be active on one account.
• Optional IPv4 and IPv6 CIDRs restrict where a key may be used. An empty list means unrestricted.
• Rotation preserves the service-account identity and can keep the predecessor valid for a bounded handover.
• Revocation rejects the key immediately on every API endpoint.

Dataset endpoints

Every path below is relative to https://api.tradepolaris.com/platform/v1. The integration surface is structured and read-only; callers cannot submit SQL or arbitrary ordering.

Pagination without silent truncation

Point-in-time queries are capability-based

Use as_of=YYYY-MM-DD only when the resolved schema says capabilities.point_in_time_supported: true. The bound means “known by the end of that UTC date” on the declared availability field. Unsupported datasets return 400 instead of silently ignoring the bound.

Coverage is dataset- and version-specific. Inspect date_min and date_max; Kappa makes no catalog-wide history promise. See the complete machine-readable capability matrix.

US equity reference data includes active and inactive/delisted symbols where supplied. That reduces survivorship bias but does not certify every dataset or historical universe as survivorship-free.

Handle exports as short-lived bearer artifacts

• Download the returned URL with a plain GET. Do not attach the TradePolaris API key to the object-storage request.
• Verify content_sha256 before accepting the file. Versions are immutable, so a pinned re-download should be byte-identical.
• Do not log, share, or persist the URL. Anyone holding it can download until it expires.
• Revoking the API key does not invalidate URLs already issued; their TTL is the remaining exposure window.
• The URL-bearing response is Cache-Control: no-store.
• The export endpoint does not support as_of. Use a point-in-time CSV query when the filtered result fits the documented row ceiling.

Errors and retries

The default normal-capacity budget is 120 requests per minute per key and can vary by plan. On 429, wait for Retry-After. Retry transient 503 responses with capped exponential backoff.

400

The request asks for unsupported semantics, such as as_of on a dataset that does not declare point-in-time support.

401

The bearer key is missing, malformed, expired, revoked, or unknown.

402 dataset_limit

The monthly distinct-dataset export meter is exhausted.

403

The account is not entitled to Data API access, or the key's source-CIDR policy denies the trusted client address.

404

The dataset does not exist or is outside this key's scope. Private datasets are concealed rather than disclosed with 403.

413

The preview is too large, or a CSV query matches more than 1,000,000 rows. Narrow the query or use Parquet export.

422

One or more parameters failed validation.

429

The per-key request budget is spent. Wait for Retry-After, then retry.

503

A transient fail-closed service guard rejected the request. Retry with backoff.

Key-management routes use account authentication

A Data API key cannot create, list, rotate, edit, or revoke other keys. These routes require an authenticated TradePolaris account session or account JWT. Ownership comes from that identity and cannot be supplied in the request body.

POST /api-keys

Create a key and return its secret once.

GET /api-keys

List credential history and metadata; never returns secrets.

POST /api-keys/{id}/rotate

Create a same-principal successor with a bounded overlap.

PATCH /api-keys/{id}

Update the label or source-CIDR policy.

DELETE /api-keys/{id}

Revoke immediately while retaining credential history.

One contract for people and machines

The page is server-rendered with semantic headings, tables, code, and stable fragment IDs. Parsers can use the same reference in two machine-oriented formats:

The root llms.txt file links these artifacts so an agent discovering TradePolaris from the site index can reach the integration contract directly.