> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/data-warehouse/introduction/export.md). # Export Every list endpoint exposes an asynchronous export. The export runs as a background job and produces a downloadable file. Use it for large result sets instead of paging through the list endpoint. Three actions are available on each list endpoint: | Action | Path | Purpose | | --------------- | --------------------------- | --------------------------------------------------------- | | Field discovery | `{endpoint}/export_info/` | Returns the exportable fields and supported file formats. | | Start export | `{endpoint}/export/` | Starts a background job and returns a `cache_key`. | | Check status | `{endpoint}/export_status/` | Returns the job status and the download URL. | Replace `{endpoint}` with the same path segment the list endpoint uses, for example `baskets/baskets` or `orders/order-items`. Each endpoint section shows this segment in its own path. Every list endpoint in this documentation offers all three actions, so any path you find here can be exported. #### Step 1. Discover the Exportable Fields ```bash GET {endpoint}/export_info/ ``` ```json { "fields": ["id", "status", "user_id", "user__email", "created_date"], "default_fields": ["id", "status", "user_id", "user__email", "created_date"], "available_export_formats": ["xls"], "default_export_format": "xls" } ``` * `fields` lists every field you may request. * `default_fields` lists the fields used when you request none. > **Note:** The exportable fields are not always the same as the fields the list endpoint returns. An export can expose related values, such as a user email address, that the list response reports only as a numeric ID. Call `export_info` before you build an export request. #### Step 2. Start the Export ```bash GET {endpoint}/export/?fields=id&fields=user__email&status=active ``` Supported parameters: * `fields`: A field to include. Repeat the parameter for each field. The API ignores any value that `export_info` does not list, and falls back to `default_fields` when no valid field remains. * `limit`: The maximum number of records to export. Omit it to export every matching record. The 1000-record page-size cap applies to list responses only and does not restrict an export. * `export_format`: The output format. `xls` is currently the only supported value, and it is also the default. Any other value returns `400 Bad Request`. * Any filter the list endpoint supports. The export applies the same filters. The response returns the key you poll with: ```json { "cache_key": "ace40858-1c3f-4c1a-9f0d-7b2c9b2f9a11", "is_ready": false, "url": null, "error_message": null } ``` An unsupported `export_format` returns `400 Bad Request`: ```json { "error_message": "Unsupported file format. Supported formats: xls." } ``` > **Note:** The `error_message` text is translated into the language the instance is configured for, so its wording varies between environments. Branch on the status code, not on the message string. #### Step 3. Poll for the Result ```bash GET {endpoint}/export_status/?cache_key=ace40858-1c3f-4c1a-9f0d-7b2c9b2f9a11 ``` While the job runs, `is_ready` stays `false` and `url` stays `null`. When the job finishes, the response carries the download URL: ```json { "cache_key": "ace40858-1c3f-4c1a-9f0d-7b2c9b2f9a11", "is_ready": true, "url": "https:///exports/basket_export_321a4268.xls", "error_message": null } ``` A failed job also reports `is_ready` as `true`, but `url` stays `null` and `error_message` describes the failure: ```json { "cache_key": "ace40858-1c3f-4c1a-9f0d-7b2c9b2f9a11", "is_ready": true, "url": null, "error_message": "Storage error" } ``` Treat any response where `is_ready` is `true` and `url` is `null` as a failed export. Start a new export rather than retrying the same `cache_key`. An unknown or expired `cache_key` returns `404 Not Found`: ```json { "cache_key": "ace40858-1c3f-4c1a-9f0d-7b2c9b2f9a11", "is_ready": false, "url": null, "error_message": "Export not found or expired" } ``` A request without the `cache_key` parameter also returns `404 Not Found`, with an empty response body. Poll this endpoint until `is_ready` is `true`. The export is a queued background job, so the time to completion depends on the size of the result set and on the current load of the queue rather than on a fixed duration. The API defines no polling interval; choose one that suits your integration and stop polling when the one-hour window described below expires. > **Note:** A large export is split across sheets named `Sheet1`, `Sheet2`, and so on. Each sheet carries its own header row and up to 65,534 records. Read every sheet in the file. Reading only the first sheet silently drops every record beyond it. > **Warning:** The export status expires one hour after the job finishes. After that, `export_status` returns `404 Not Found` for that `cache_key` and you must start a new export. Download the file within that hour, or store its URL. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://apidocs.akinon.com/commerce-openapis/data-warehouse/introduction/export.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.