Docs/Guides/Export to CSV

Exporting data to CSV

This guide shows two ways to get Ptolemy data into CSV format: the asynchronous Export API for large datasets, and direct filter API iteration for smaller exports.

Choose your approach

Export API (recommended for large datasets)

Submit an export job and download the resulting file. Best for full workspace exports, scheduled backups, or datasets over 10,000 rows. The file is ready when status=completed.

Filter API + client-side CSV

Paginate through the filter API and write rows yourself. Best for small datasets, custom column selection, or when you need to transform data before writing.

Method 1 — Export API

Submit an export job, poll until complete, then download the pre-signed URL:

import time, requests

# Submit export job
job = client.post("/exports", json={
  "object_type": "instruments",
  "format": "csv",
  "include_archived": False
}).json()

# Poll until complete
while job["status"] in ("queued", "processing"):
  time.sleep(5)
  job = client.get(f"/exports/{job['id']}").json()

if job["status"] != "completed":
  raise RuntimeError(f"Export failed: {job['status']}")

# Download the file
csv_data = requests.get(job["download_url"]).content
with open("instruments.csv", "wb") as f:
  f.write(csv_data)

The download_url is a pre-signed URL that expires 15 minutes after generation. Download the file as soon as the job completes.

Method 2 — Filter API with client-side CSV

For custom exports, paginate through the filter API and build the CSV yourself:

import csv, io

output = io.StringIO()
writer = None
cursor = None

while True:
  resp = client.post("/instruments/filter", json={
    "type_id": "equity", "limit": 500,
    **({"after": cursor} if cursor else {})
  }).json()
  
  for inst in resp["data"]:
    row = {"id": inst["id"], "name": inst["name"], **inst.get("extra_fields_snapshot", {})}
    if writer is None:
      writer = csv.DictWriter(output, fieldnames=row.keys())
      writer.writeheader()
    writer.writerow(row)

  if not resp["meta"]["has_more"]: break
  cursor = resp["meta"]["next_cursor"]

with open("equity_instruments.csv", "w") as f:
  f.write(output.getvalue())

Exporting time series data

Time series data can also be exported via the Export API. For scalar values, each row contains instrument_id, type_id, timestamp, and value. For composite values, items are flattened to individual columns:

Export OHLCV bars to CSV

POST /exports

{
  "object_type": "composite_time_series_values",
  "format": "csv",
  "filter": {
    "and": [
      { "field": "type_id", "op": "eq", "value": "ohlcv-daily" }
    ]
  }
}