Skip to main content
POST
/
v1
/
export
/
jobs
Create Export Job
curl --request POST \
  --url https://api.shoal.xyz/v1/export/jobs \
  --header 'Authorization: Bearer <token>'
Use export jobs when you need warehouse backfill, archive sync, or other bulk historical transfer. Do not use feed, replay, or timeline routes as a substitute for export.

​
Access

  • Access layer: premium
  • Plan floor: enterprise
  • Surface: export

​
Request Body

FieldTypeRequiredDescription
scopestringYesOne of organizations.registry, radar.history, signal.history, replay.global, timeline.by-organization
formatstringYesOne of jsonl, csv, parquet
sincestringConditionalISO 8601 timestamp; required for historical scopes
untilstringNoISO 8601 timestamp; must be later than since
organizationIdsinteger[]ConditionalRequired for timeline.by-organization exports
categorystringNoOptional category filter
includeEvidencebooleanNoInclude evidence-rich output when supported
notestringNoOptional job note, max 500 characters

​
Request

cURL
curl -X POST "https://api.shoal.xyz/v1/export/jobs" \
  -H "Authorization: Bearer YOUR_ENTERPRISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "replay.global",
    "format": "jsonl",
    "since": "2026-04-01T00:00:00Z",
    "until": "2026-04-10T00:00:00Z",
    "includeEvidence": true,
    "note": "Internal warehouse backfill for April incident review"
  }'

​
Response (201)

{
  "data": {
    "id": "d9d2a2e6-2df2-45ef-9f08-2e1ab36ef8e0",
    "appUserId": "app_user_123",
    "apiKeyId": 17,
    "scope": "replay.global",
    "format": "jsonl",
    "status": "requested",
    "requestedParams": {
      "since": "2026-04-01T00:00:00.000Z",
      "until": "2026-04-10T00:00:00.000Z",
      "category": null,
      "includeEvidence": true,
      "organizationIds": []
    },
    "note": "Internal warehouse backfill for April incident review",
    "downloadUrl": null,
    "expiresAt": null,
    "error": null,
    "createdAt": "2026-04-11T20:15:00.000Z",
    "updatedAt": "2026-04-11T20:15:00.000Z"
  }
}

​
Notes

  • Export jobs are explicit enterprise workflows, not ordinary paginated API usage.
  • Historical scopes require since.
  • timeline.by-organization requires organizationIds.
  • This route records the request only. Delivery and fulfillment happen asynchronously.

​
Errors

  • 400 for invalid scope, format, or timestamps
  • 403 if the API key does not meet the enterprise plan floor
  • 500 on internal server error