Data Exports

API reference for creating and retrieving data exports.

The Data Exports service lets you export platform data as CSV or JSON files. Exports run asynchronously -- you create an export request and then poll for completion or wait for a webhook notification.

Create an export

POST /api/v1/exports

Scope: exports:create

Request body

Field	Type	Required	Description
dataType	string	Yes	What to export: messages, usage, webhooks, or invoices
format	string	No	Output format: CSV or JSON. Default: CSV
filters.dateFrom	string	No	ISO 8601 start date for the export window
filters.dateTo	string	No	ISO 8601 end date for the export window
filters.service	string	No	Filter by service name (e.g., email, sms, storage)

Response

{
  "success": true,
  "data": {
    "id": "exp_abc123",
    "organizationId": "org_xyz",
    "dataType": "usage",
    "format": "CSV",
    "status": "PENDING",
    "downloadUrl": null,
    "fileSize": null,
    "recordCount": null,
    "completedAt": null,
    "expiresAt": null,
    "createdAt": "2026-04-05T10:00:00.000Z"
  }
}

Field	Type	Description
id	string	Export ID for polling
dataType	string	The data type being exported
format	string	Output format
status	string	PENDING, PROCESSING, COMPLETED, or FAILED
downloadUrl	string or null	Pre-signed download URL (available when COMPLETED)
fileSize	number or null	File size in bytes (available when COMPLETED)
recordCount	number or null	Number of records exported (available when COMPLETED)
completedAt	string or null	ISO 8601 completion timestamp
expiresAt	string or null	ISO 8601 expiry timestamp for the download URL

Get an export

GET /api/v1/exports/:exportId

Scope: exports:create

Returns the export record. Poll this endpoint to check when status transitions to COMPLETED, then use the downloadUrl to retrieve the file.

Export statuses

Status	Description
PENDING	Export has been queued
PROCESSING	Export is being generated
COMPLETED	Export is ready for download
FAILED	Export generation failed (check error details)

Processor configuration

The exports processor controls format restrictions, row limits, and file retention. See Exports Processor Config for the full reference.

Setting	Default	Description
allowedFormats	["csv", "json"]	Which formats tenants can request
maxRowsPerExport	100000	Maximum rows per export file
retentionDays	30	Days before completed export files are auto-deleted

Examples

Export usage data as CSV

curl

# Create the export
curl -X POST https://api.platformxe.com/api/v1/exports \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "dataType": "usage",
    "format": "CSV",
    "filters": {
      "dateFrom": "2026-03-01T00:00:00.000Z",
      "dateTo": "2026-03-31T23:59:59.999Z",
      "service": "email"
    }
  }'

# Poll for completion
curl https://api.platformxe.com/api/v1/exports/exp_abc123 \
  -H "x-api-key: pxk_live_your_api_key_here"

TypeScript SDK

import { PlatformXe } from '@caldera/platformxe-sdk';

const px = new PlatformXe({ apiKey: 'pxk_live_your_api_key_here' });

// Create export
const exp = await px.exports.create({
  dataType: 'usage',
  format: 'CSV',
  filters: {
    dateFrom: '2026-03-01T00:00:00.000Z',
    dateTo: '2026-03-31T23:59:59.999Z',
    service: 'email',
  },
});

console.log(exp.id, exp.status);
// "exp_abc123" "PENDING"

// Poll for completion
const completed = await px.exports.get(exp.id);
if (completed.status === 'COMPLETED') {
  console.log('Download:', completed.downloadUrl);
}

Python SDK

from platformxe import PlatformXe

px = PlatformXe(api_key="pxk_live_your_api_key_here")

exp = px.exports.create({
    "dataType": "usage",
    "format": "CSV",
    "filters": {
        "dateFrom": "2026-03-01T00:00:00.000Z",
        "dateTo": "2026-03-31T23:59:59.999Z",
        "service": "email"
    }
})

# Poll for completion
result = px.exports.get(exp["id"])
if result["status"] == "COMPLETED":
    print("Download:", result["downloadUrl"])

Export invoices as JSON

const invoiceExport = await px.exports.create({
  dataType: 'invoices',
  format: 'JSON',
  filters: {
    dateFrom: '2026-01-01T00:00:00.000Z',
  },
});

Error responses

Code	Description
BAD_REQUEST	Invalid dataType, format, or filter values
FORBIDDEN	API key does not have the exports:create scope
SERVICE_DISABLED	Exports processor is disabled for this organization
RATE_LIMITED	Rate limit exceeded