Docs/API Reference/Import & Export

Import & Export

The Import & Export API lets you bulk-load data from CSV or JSON files and export workspace data for backup or migration. Imports and exports are processed asynchronously — you submit a job and poll for completion.

/v1/workspaces/{workspaceId}

Imports Exports File Formats

Imports

Import jobs process CSV or JSON files uploaded to Ptolemy. Each import job targets a single resource type (e.g. instruments, time series values). Rows are validated and inserted in batches; partial imports are possible if on_error is set to continue.

Import files are accepted via multipart/form-data upload. The maximum file size is 100 MB. For larger datasets, split into multiple import jobs.

GET/importsList import jobsViewer+▶

POST/importsCreate an import jobMember▶

Uploads a file and creates an import job. Send as multipart/form-data with the file as the file field.

Request (multipart/form-data fields)

file: <binary CSV or JSON file>
resource_type: "instruments"
on_error: "abort"
identifier_column: "identifier"

Response — 202 Accepted

{
  "id": "uuid",
  "status": "queued",
  "resource_type": "instruments",
  "row_count": null,
  "created_at": "2026-04-15T09:00:00Z"
}

GET/imports/{id}Get an import jobViewer+▶

POST/imports/{id}/cancelCancel an import jobMember▶

Status	Meaning
`queued`	Job received, waiting for a worker to pick it up
`processing`	Worker is actively importing rows
`completed`	All rows processed (some may have failed if on_error=continue)
`failed`	Job failed before completing (check errors array)
`cancelled`	Job was cancelled by the user

Exports

Export jobs produce a downloadable file containing all data of a given resource type from the workspace. Exports run asynchronously and the download URL is provided when the job completes.

GET/exportsList export jobsViewer+▶

POST/exportsCreate an export jobMember▶

Creates an export job. Supports optional filter conditions to export a subset of records.

Request body

{
  "object_type": "instruments",
  "format": "csv",
  "include_archived": false,
  "filter": {
    "and": [ { "field": "type_id", "op": "eq", "value": "equity" }]
  }
}

Response — 202 Accepted

{
  "id": "uuid",
  "status": "queued",
  "object_type": "instruments",
  "format": "csv",
  "download_url": null,
  "created_at": "2026-04-15T09:00:00Z"
}

GET/exports/{id}Get an export jobViewer+▶

File Formats

Both imports and exports support CSV and JSON formats. The structure varies slightly by resource type.

CSV imports

The first row must be a header row. Column names must match the field identifiers for the resource type. Extra columns are ignored. Use identifier_column to specify which column uniquely identifies each row for upsert behaviour.

JSON imports

Must be a JSON array of objects. Each object represents one row and must include all required fields. Nested objects are supported for field_values and extras.

Resource type	Importable	Exportable	Notes
`instruments`	Yes	Yes	Includes field_values columns
`time_series_values`	Yes	Yes	instrument_id and type_id may be identifiers or UUIDs
`composite_time_series_values`	Yes	Yes	Items are flattened to individual columns in CSV
`markets`	Yes	Yes	Includes field_values columns
`market_listings`	Yes	Yes
`market_listing_suspensions`	Yes	Yes
`market_calendars`	No	Yes	Export only — create via API