TradePolaris Data API

Make your first request

Search for a dataset and inspect its schema before choosing filters, so you never guess 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

import { createHash } from "node:crypto";

const BASE_URL = "https://api.tradepolaris.com/platform/v1";
const API_KEY = process.env.TP_API_KEY;
if (!API_KEY) throw new Error("Set TP_API_KEY in the server environment");

const sleep = (milliseconds: number) =>
  new Promise((resolve) => setTimeout(resolve, milliseconds));

async function api(path: string): Promise<Response> {
  const url = new URL(path, BASE_URL + "/");
  if (url.origin !== new URL(BASE_URL).origin) {
    throw new Error("Refusing to forward API auth to another origin");
  }
  for (let attempt = 0; attempt < 5; attempt += 1) {
    const response = await fetch(url, {
      headers: { Authorization: "Bearer " + API_KEY },
    });
    if (![429, 503].includes(response.status) || attempt === 4) return response;
    const seconds = Number(response.headers.get("Retry-After"));
    const delay = Number.isFinite(seconds) && seconds > 0
      ? Math.min(seconds * 1000, 5000)
      : Math.min(250 * 2 ** attempt, 5000);
    await sleep(delay);
  }
  throw new Error("unreachable");
}

async function json(path: string) {
  const response = await api(path);
  if (!response.ok) throw new Error("Data API returned " + response.status);
  return response.json();
}

const catalog = await json("datasets?q=example&limit=10");
if (!catalog[0]) throw new Error("No matching dataset");
const name = catalog[0].name;
const version = catalog[0].latest_version; // pin every following request
const route = "datasets/" + encodeURIComponent(name);
const schema = await json(route + "/schema?version=" + version);

let offset = 0;
const rows: unknown[][] = [];
for (let pageNumber = 0; pageNumber < 20; pageNumber += 1) {
  const page = await json(
    route + "/query?version=" + version + "&limit=5000&offset=" + offset,
  );
  rows.push(...page.rows);
  if (!page.truncated) break;
  if (page.returned < 1 || pageNumber === 19) {
    throw new Error("Pagination did not terminate within the client bound");
  }
  offset += page.returned;
}

const artifact = await json(route + "/export?version=" + version);
const download = await fetch(artifact.url); // deliberately no Authorization header
if (!download.ok) throw new Error("Export download returned " + download.status);
const bytes = Buffer.from(await download.arrayBuffer());
const actual = createHash("sha256").update(bytes).digest("hex");
if (!artifact.content_sha256 || actual !== artifact.content_sha256) {
  throw new Error("Export checksum mismatch");
}
console.log({ columns: schema.columns.length, rows: rows.length, version });

Authentication and scopes

Send the key on every request. The secret starts with tp_live_ and is shown only once.

Authorization: Bearer tp_live_...

• Keys expire after 1–365 days (90 by default).
• Up to five keys can be active on one account.
• Optional IPv4 and IPv6 CIDRs restrict where a key works (an empty list means unrestricted).
• Rotation keeps the service-account identity, with an optional bounded overlap.
• Revocation rejects the key immediately on every API endpoint.

A versioned contract with an explicit change trail

The current public wire contract is 1.0.0-beta.1 (beta), and CI fingerprints its endpoints, parameters, response fields, headers and error shapes against the latest changelog entry.

Read the HTML changelog, JSON feed, or Markdown feed. The /health and /ready routes are operational diagnostics outside this five-operation contract and do not define supported integration behavior.

Dataset endpoints

Paths are relative to https://api.tradepolaris.com/platform/v1, and the read-only surface accepts no 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, and Kappa makes no catalog-wide history promise, so inspect date_min and date_max. See the complete machine-readable capability matrix.

US equity reference data includes active and inactive/delisted symbols where supplied. That reduces survivorship bias; it does not certify any dataset or any reconstructed universe as complete. The us-listing-status lane records dated listing and delisting events for those symbols, so membership on a date can be rebuilt from the events effective on or before it, down to a 2005-01-01 floor. It is not index membership, it carries no delisting reason, and listing dates below that floor are not recoverable from it. Its membership is inclusive of non-common security types. See that lane's row for the security_class column that separates them.

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 (its response is Cache-Control: no-store). Anyone holding it can download until it expires.
• Revoking the API key does not invalidate issued URLs, which stay valid until their TTL ends.
• 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 manage keys. These routes need a TradePolaris account session or account JWT, and ownership comes from that identity, never from the request body.

POST /api-keys

Create a key and return its secret once.

GET /api-keys

List credential history and metadata, never 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

This page is server-rendered with semantic headings, tables, code and stable fragment IDs, and the same reference is available as OpenAPI and Markdown.

The root llms.txt links these files so agents can reach the integration contract from the site index.