> For the complete documentation index, see [llms.txt](https://developers.whaly.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.whaly.io/rest-api/api-reference/exports.md).

# Exports

## GET /v1/exports

> List the exports granted to this service account.

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PaginatedListWrapper":{"type":"object","properties":{"paging":{"$ref":"#/components/schemas/PagingInfo"}},"required":["paging"]},"PagingInfo":{"type":"object","properties":{"next":{"$ref":"#/components/schemas/PagingNext"}},"required":["next"]},"PagingNext":{"type":"object","properties":{"after":{"type":"string"}},"required":["after"]},"ExportDefinitionDto":{"type":"object","properties":{"id":{"type":"string","description":"Public id of the export (expt_…), used in every path."},"reference_id":{"type":"string","description":"The export's reference id in Whaly."},"name":{"type":"string","description":"Display name."},"object":{"$ref":"#/components/schemas/ExportObjectRefDto"},"format":{"type":"string","enum":["jsonl.gz"],"description":"gzip-compressed JSON lines."},"primary_key":{"description":"The output columns that identify a row. Rows are sorted by them.","type":"array","items":{"type":"string"}},"columns":{"description":"The output schema, in column order.","type":"array","items":{"$ref":"#/components/schemas/ExportColumnDto"}},"schema_version":{"type":"number","description":"Incremented on every change of the output schema."},"schema_hash":{"type":"string","description":"sha256 of the public schema (names, types, nullability, order)."},"last_succeeded_run":{"nullable":true,"description":"The most recent successful run.","allOf":[{"$ref":"#/components/schemas/ExportRunRefDto"}]}},"required":["id","reference_id","name","object","format","primary_key","columns","schema_version","schema_hash","last_succeeded_run"]},"ExportObjectRefDto":{"type":"object","properties":{"id":{"type":"string","description":"Public id of the exported Object."},"reference_id":{"type":"object","description":"Reference id of the exported Object.","nullable":true}},"required":["id","reference_id"]},"ExportColumnDto":{"type":"object","properties":{"name":{"type":"string","description":"Output column name, as written in every row. Fixed by the export, never by internal names."},"type":{"type":"string","enum":["string","integer","decimal","float","boolean","date","datetime"],"description":"How to parse the value. Every row is one JSON object per line, with every key present on every row (null when empty).\nNumbers are JSON strings: integer as base-10 digits (\"184\"), decimal in plain notation (\"1312.50\"), float as the\nshortest text that parses back to the same double, which may use an exponent (\"5e-324\"). NaN, ±Infinity and infinite\ndates are null. date is YYYY-MM-DD, datetime is ISO 8601 in UTC with microseconds and a Z. Ignore keys you do not know:\nnew columns are added at the end without notice."},"nullable":{"type":"boolean","description":"Whether the value can be null."}},"required":["name","type","nullable"]},"ExportRunRefDto":{"type":"object","properties":{"id":{"type":"string","description":"Public id of the run."},"completed_at":{"type":"object","description":"When it completed (ISO 8601).","nullable":true}},"required":["id","completed_at"]}}},"paths":{"/v1/exports":{"get":{"operationId":"ExportsController_listAll","summary":"List the exports granted to this service account.","parameters":[{"name":"after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedListWrapper"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ExportDefinitionDto"}}}}]}}}}}}}}}
```

## GET /v1/exports/{exportId}

> One export: its output schema and last successful run.

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"ExportDefinitionDto":{"type":"object","properties":{"id":{"type":"string","description":"Public id of the export (expt_…), used in every path."},"reference_id":{"type":"string","description":"The export's reference id in Whaly."},"name":{"type":"string","description":"Display name."},"object":{"$ref":"#/components/schemas/ExportObjectRefDto"},"format":{"type":"string","enum":["jsonl.gz"],"description":"gzip-compressed JSON lines."},"primary_key":{"description":"The output columns that identify a row. Rows are sorted by them.","type":"array","items":{"type":"string"}},"columns":{"description":"The output schema, in column order.","type":"array","items":{"$ref":"#/components/schemas/ExportColumnDto"}},"schema_version":{"type":"number","description":"Incremented on every change of the output schema."},"schema_hash":{"type":"string","description":"sha256 of the public schema (names, types, nullability, order)."},"last_succeeded_run":{"nullable":true,"description":"The most recent successful run.","allOf":[{"$ref":"#/components/schemas/ExportRunRefDto"}]}},"required":["id","reference_id","name","object","format","primary_key","columns","schema_version","schema_hash","last_succeeded_run"]},"ExportObjectRefDto":{"type":"object","properties":{"id":{"type":"string","description":"Public id of the exported Object."},"reference_id":{"type":"object","description":"Reference id of the exported Object.","nullable":true}},"required":["id","reference_id"]},"ExportColumnDto":{"type":"object","properties":{"name":{"type":"string","description":"Output column name, as written in every row. Fixed by the export, never by internal names."},"type":{"type":"string","enum":["string","integer","decimal","float","boolean","date","datetime"],"description":"How to parse the value. Every row is one JSON object per line, with every key present on every row (null when empty).\nNumbers are JSON strings: integer as base-10 digits (\"184\"), decimal in plain notation (\"1312.50\"), float as the\nshortest text that parses back to the same double, which may use an exponent (\"5e-324\"). NaN, ±Infinity and infinite\ndates are null. date is YYYY-MM-DD, datetime is ISO 8601 in UTC with microseconds and a Z. Ignore keys you do not know:\nnew columns are added at the end without notice."},"nullable":{"type":"boolean","description":"Whether the value can be null."}},"required":["name","type","nullable"]},"ExportRunRefDto":{"type":"object","properties":{"id":{"type":"string","description":"Public id of the run."},"completed_at":{"type":"object","description":"When it completed (ISO 8601).","nullable":true}},"required":["id","completed_at"]}}},"paths":{"/v1/exports/{exportId}":{"get":{"operationId":"ExportsController_findOne","summary":"One export: its output schema and last successful run.","parameters":[{"name":"exportId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportDefinitionDto"}}}},"404":{"description":"Unknown, or not granted to this service account."}}}}}}
```

## GET /v1/exports/{exportId}/runs

> Run history, newest first. status=succeeded\&limit=1 is the latest good extract.

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PaginatedListWrapper":{"type":"object","properties":{"paging":{"$ref":"#/components/schemas/PagingInfo"}},"required":["paging"]},"PagingInfo":{"type":"object","properties":{"next":{"$ref":"#/components/schemas/PagingNext"}},"required":["next"]},"PagingNext":{"type":"object","properties":{"after":{"type":"string"}},"required":["after"]},"ExportRunDto":{"type":"object","properties":{"id":{"type":"string","description":"Public id of the run."},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled","expired"],"description":"expired: succeeded, but its files were deleted (7 days after completion)."},"trigger":{"type":"string","enum":["api","factory"]},"created_at":{"type":"object","nullable":true},"started_at":{"type":"object","nullable":true},"snapshot_at":{"type":"object","nullable":true,"description":"Every row reflects the data as of this instant."},"completed_at":{"type":"object","nullable":true},"expires_at":{"type":"object","nullable":true,"description":"When the files are deleted."},"row_count":{"type":"object","nullable":true},"size_bytes":{"type":"object","nullable":true},"schema_version":{"type":"object","nullable":true},"schema_hash":{"type":"object","nullable":true},"manifest":{"nullable":true,"description":"manifest.json, written last: it lists the parts and their checksums.","allOf":[{"$ref":"#/components/schemas/SignedUrlDto"}]},"files":{"description":"The parts, in key order. Every row is one JSON object per line, with every key present on every row (null when empty).\nNumbers are JSON strings: integer as base-10 digits (\"184\"), decimal in plain notation (\"1312.50\"), float as the\nshortest text that parses back to the same double, which may use an exponent (\"5e-324\"). NaN, ±Infinity and infinite\ndates are null. date is YYYY-MM-DD, datetime is ISO 8601 in UTC with microseconds and a Z. Ignore keys you do not know:\nnew columns are added at the end without notice.","type":"array","items":{"$ref":"#/components/schemas/ExportFileDto"}},"error":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ExportRunErrorDto"}]}},"required":["id","status","trigger","created_at","started_at","snapshot_at","completed_at","expires_at","row_count","size_bytes","schema_version","schema_hash","manifest","files","error"]},"SignedUrlDto":{"type":"object","properties":{"url":{"type":"string","description":"A signed GCS URL, valid for 15 minutes. Treat it as a credential."},"url_expires_at":{"type":"string","description":"When the URL stops working (ISO 8601)."}},"required":["url","url_expires_at"]},"ExportFileDto":{"type":"object","properties":{"name":{"type":"string"},"row_count":{"type":"number","description":"Rows in this part (at most 1,000,000)."},"size_bytes":{"type":"number","description":"Size of the gzip file in bytes."},"sha256":{"type":"string","description":"sha256 of the gzip file, hex."},"url":{"type":"object","nullable":true,"description":"Signed download URL, valid for 15 minutes."},"url_expires_at":{"type":"object","nullable":true}},"required":["name","row_count","size_bytes","sha256","url","url_expires_at"]},"ExportRunErrorDto":{"type":"object","properties":{"kind":{"type":"string","enum":["member_unavailable","plan_unsafe","data_reorganized","cast_failed","timeout","worker_lost","definition_invalid","cancelled","internal"]},"message":{"type":"string"},"step":{"type":"string","nullable":true,"enum":["plan","stream","storage","finalize","worker"],"description":"Where the run failed."}},"required":["kind","message","step"]}}},"paths":{"/v1/exports/{exportId}/runs":{"get":{"operationId":"ExportsController_listRuns","summary":"Run history, newest first. status=succeeded&limit=1 is the latest good extract.","parameters":[{"name":"after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}},{"name":"status","required":false,"in":"query","schema":{"enum":["queued","running","succeeded","failed","cancelled"],"type":"string"}},{"name":"exportId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedListWrapper"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ExportRunDto"}}}}]}}}}}}}}}
```

## GET /v1/exports/{exportId}/runs/{runId}

> One run, with signed URLs for its manifest and parts once it succeeded.

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"ExportRunDto":{"type":"object","properties":{"id":{"type":"string","description":"Public id of the run."},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled","expired"],"description":"expired: succeeded, but its files were deleted (7 days after completion)."},"trigger":{"type":"string","enum":["api","factory"]},"created_at":{"type":"object","nullable":true},"started_at":{"type":"object","nullable":true},"snapshot_at":{"type":"object","nullable":true,"description":"Every row reflects the data as of this instant."},"completed_at":{"type":"object","nullable":true},"expires_at":{"type":"object","nullable":true,"description":"When the files are deleted."},"row_count":{"type":"object","nullable":true},"size_bytes":{"type":"object","nullable":true},"schema_version":{"type":"object","nullable":true},"schema_hash":{"type":"object","nullable":true},"manifest":{"nullable":true,"description":"manifest.json, written last: it lists the parts and their checksums.","allOf":[{"$ref":"#/components/schemas/SignedUrlDto"}]},"files":{"description":"The parts, in key order. Every row is one JSON object per line, with every key present on every row (null when empty).\nNumbers are JSON strings: integer as base-10 digits (\"184\"), decimal in plain notation (\"1312.50\"), float as the\nshortest text that parses back to the same double, which may use an exponent (\"5e-324\"). NaN, ±Infinity and infinite\ndates are null. date is YYYY-MM-DD, datetime is ISO 8601 in UTC with microseconds and a Z. Ignore keys you do not know:\nnew columns are added at the end without notice.","type":"array","items":{"$ref":"#/components/schemas/ExportFileDto"}},"error":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ExportRunErrorDto"}]}},"required":["id","status","trigger","created_at","started_at","snapshot_at","completed_at","expires_at","row_count","size_bytes","schema_version","schema_hash","manifest","files","error"]},"SignedUrlDto":{"type":"object","properties":{"url":{"type":"string","description":"A signed GCS URL, valid for 15 minutes. Treat it as a credential."},"url_expires_at":{"type":"string","description":"When the URL stops working (ISO 8601)."}},"required":["url","url_expires_at"]},"ExportFileDto":{"type":"object","properties":{"name":{"type":"string"},"row_count":{"type":"number","description":"Rows in this part (at most 1,000,000)."},"size_bytes":{"type":"number","description":"Size of the gzip file in bytes."},"sha256":{"type":"string","description":"sha256 of the gzip file, hex."},"url":{"type":"object","nullable":true,"description":"Signed download URL, valid for 15 minutes."},"url_expires_at":{"type":"object","nullable":true}},"required":["name","row_count","size_bytes","sha256","url","url_expires_at"]},"ExportRunErrorDto":{"type":"object","properties":{"kind":{"type":"string","enum":["member_unavailable","plan_unsafe","data_reorganized","cast_failed","timeout","worker_lost","definition_invalid","cancelled","internal"]},"message":{"type":"string"},"step":{"type":"string","nullable":true,"enum":["plan","stream","storage","finalize","worker"],"description":"Where the run failed."}},"required":["kind","message","step"]}}},"paths":{"/v1/exports/{exportId}/runs/{runId}":{"get":{"operationId":"ExportsController_findRun","summary":"One run, with signed URLs for its manifest and parts once it succeeded.","parameters":[{"name":"runId","required":true,"in":"path","schema":{"type":"string"}},{"name":"exportId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportRunDto"}}}},"404":{"description":"Unknown run, or export not granted."},"410":{"description":"The run expired: its files are gone."}}}}}}
```

## Start a run.

> Returns 202 with a new run, or 200 with the run already queued or running. One run per export at a time; runs of one organization execute one after the other.

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"ExportRunDto":{"type":"object","properties":{"id":{"type":"string","description":"Public id of the run."},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled","expired"],"description":"expired: succeeded, but its files were deleted (7 days after completion)."},"trigger":{"type":"string","enum":["api","factory"]},"created_at":{"type":"object","nullable":true},"started_at":{"type":"object","nullable":true},"snapshot_at":{"type":"object","nullable":true,"description":"Every row reflects the data as of this instant."},"completed_at":{"type":"object","nullable":true},"expires_at":{"type":"object","nullable":true,"description":"When the files are deleted."},"row_count":{"type":"object","nullable":true},"size_bytes":{"type":"object","nullable":true},"schema_version":{"type":"object","nullable":true},"schema_hash":{"type":"object","nullable":true},"manifest":{"nullable":true,"description":"manifest.json, written last: it lists the parts and their checksums.","allOf":[{"$ref":"#/components/schemas/SignedUrlDto"}]},"files":{"description":"The parts, in key order. Every row is one JSON object per line, with every key present on every row (null when empty).\nNumbers are JSON strings: integer as base-10 digits (\"184\"), decimal in plain notation (\"1312.50\"), float as the\nshortest text that parses back to the same double, which may use an exponent (\"5e-324\"). NaN, ±Infinity and infinite\ndates are null. date is YYYY-MM-DD, datetime is ISO 8601 in UTC with microseconds and a Z. Ignore keys you do not know:\nnew columns are added at the end without notice.","type":"array","items":{"$ref":"#/components/schemas/ExportFileDto"}},"error":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ExportRunErrorDto"}]}},"required":["id","status","trigger","created_at","started_at","snapshot_at","completed_at","expires_at","row_count","size_bytes","schema_version","schema_hash","manifest","files","error"]},"SignedUrlDto":{"type":"object","properties":{"url":{"type":"string","description":"A signed GCS URL, valid for 15 minutes. Treat it as a credential."},"url_expires_at":{"type":"string","description":"When the URL stops working (ISO 8601)."}},"required":["url","url_expires_at"]},"ExportFileDto":{"type":"object","properties":{"name":{"type":"string"},"row_count":{"type":"number","description":"Rows in this part (at most 1,000,000)."},"size_bytes":{"type":"number","description":"Size of the gzip file in bytes."},"sha256":{"type":"string","description":"sha256 of the gzip file, hex."},"url":{"type":"object","nullable":true,"description":"Signed download URL, valid for 15 minutes."},"url_expires_at":{"type":"object","nullable":true}},"required":["name","row_count","size_bytes","sha256","url","url_expires_at"]},"ExportRunErrorDto":{"type":"object","properties":{"kind":{"type":"string","enum":["member_unavailable","plan_unsafe","data_reorganized","cast_failed","timeout","worker_lost","definition_invalid","cancelled","internal"]},"message":{"type":"string"},"step":{"type":"string","nullable":true,"enum":["plan","stream","storage","finalize","worker"],"description":"Where the run failed."}},"required":["kind","message","step"]}}},"paths":{"/v1/exports/{exportId}/runs":{"post":{"operationId":"ExportsController_startRun","summary":"Start a run.","description":"Returns 202 with a new run, or 200 with the run already queued or running. One run per export at a time; runs of one organization execute one after the other.","parameters":[{"name":"exportId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The run already queued or running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportRunDto"}}}},"202":{"description":"A new run, queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportRunDto"}}}},"404":{"description":"Unknown, or not granted to this service account."},"422":{"description":"The export can't run: the body names the column (a source deleted, a field not ready)."},"429":{"description":"A daily run quota is used up: the body names which, and when it frees (retry_at, Retry-After)."}}}}}}
```

## POST /v1/exports/{exportId}/runs/{runId}/cancel

> Cancel a queued or running run. A finished run is returned unchanged.

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"ExportRunDto":{"type":"object","properties":{"id":{"type":"string","description":"Public id of the run."},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled","expired"],"description":"expired: succeeded, but its files were deleted (7 days after completion)."},"trigger":{"type":"string","enum":["api","factory"]},"created_at":{"type":"object","nullable":true},"started_at":{"type":"object","nullable":true},"snapshot_at":{"type":"object","nullable":true,"description":"Every row reflects the data as of this instant."},"completed_at":{"type":"object","nullable":true},"expires_at":{"type":"object","nullable":true,"description":"When the files are deleted."},"row_count":{"type":"object","nullable":true},"size_bytes":{"type":"object","nullable":true},"schema_version":{"type":"object","nullable":true},"schema_hash":{"type":"object","nullable":true},"manifest":{"nullable":true,"description":"manifest.json, written last: it lists the parts and their checksums.","allOf":[{"$ref":"#/components/schemas/SignedUrlDto"}]},"files":{"description":"The parts, in key order. Every row is one JSON object per line, with every key present on every row (null when empty).\nNumbers are JSON strings: integer as base-10 digits (\"184\"), decimal in plain notation (\"1312.50\"), float as the\nshortest text that parses back to the same double, which may use an exponent (\"5e-324\"). NaN, ±Infinity and infinite\ndates are null. date is YYYY-MM-DD, datetime is ISO 8601 in UTC with microseconds and a Z. Ignore keys you do not know:\nnew columns are added at the end without notice.","type":"array","items":{"$ref":"#/components/schemas/ExportFileDto"}},"error":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ExportRunErrorDto"}]}},"required":["id","status","trigger","created_at","started_at","snapshot_at","completed_at","expires_at","row_count","size_bytes","schema_version","schema_hash","manifest","files","error"]},"SignedUrlDto":{"type":"object","properties":{"url":{"type":"string","description":"A signed GCS URL, valid for 15 minutes. Treat it as a credential."},"url_expires_at":{"type":"string","description":"When the URL stops working (ISO 8601)."}},"required":["url","url_expires_at"]},"ExportFileDto":{"type":"object","properties":{"name":{"type":"string"},"row_count":{"type":"number","description":"Rows in this part (at most 1,000,000)."},"size_bytes":{"type":"number","description":"Size of the gzip file in bytes."},"sha256":{"type":"string","description":"sha256 of the gzip file, hex."},"url":{"type":"object","nullable":true,"description":"Signed download URL, valid for 15 minutes."},"url_expires_at":{"type":"object","nullable":true}},"required":["name","row_count","size_bytes","sha256","url","url_expires_at"]},"ExportRunErrorDto":{"type":"object","properties":{"kind":{"type":"string","enum":["member_unavailable","plan_unsafe","data_reorganized","cast_failed","timeout","worker_lost","definition_invalid","cancelled","internal"]},"message":{"type":"string"},"step":{"type":"string","nullable":true,"enum":["plan","stream","storage","finalize","worker"],"description":"Where the run failed."}},"required":["kind","message","step"]}}},"paths":{"/v1/exports/{exportId}/runs/{runId}/cancel":{"post":{"operationId":"ExportsController_cancelRun","summary":"Cancel a queued or running run. A finished run is returned unchanged.","parameters":[{"name":"runId","required":true,"in":"path","schema":{"type":"string"}},{"name":"exportId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportRunDto"}}}}}}}}}
```
