Overview
The Asynchronous Report Export feature provides a method for exporting large report datasets via the API. Standard API requests are not suitable for reports with millions of rows, as they can require dozens of individual paginated requests to retrieve the full dataset.
This asynchronous workflow is designed to handle large data exports reliably. Instead of sending multiple requests, you can now use a simple two-step process to download the entire report in a single file.
This approach significantly reduces the number of API calls needed, allowing you to reliably export complete datasets for offline analysis or integration with external systems without impacting application performance.
Asynchronous Process: A process that runs in the background. Instead of making you wait for a large task to finish, the system accepts your request, gives you a unique ID, and lets you check the status later to get the result when it's ready. This is ideal for time-consuming tasks like exporting millions of report rows.
The Workflow
The export process involves two main steps:
Request the Report: You send an initial
POSTrequest to tell the system which report you want and what filters to apply. The system acknowledges your request and gives you a unique identifier (identifier) for the job.Check Status & Download: You use the
identifierfrom the first step to periodically check the job's status with aGETrequest. Once the status is "Completed," the response will contain a secure, time-limited URL to download your report file.
Step 1: Request the Report Export
This step initiates the background process to generate your report file.
Endpoint:
POST /v3.1/Report/async-report
Request Body
The body of your request must specify which report to run and any filters you want to apply.
Parameter | Type | Description | Required |
| String | The unique code for the report you want to export. See the Supported Reports section below for a list of available codes. | Yes |
| String | An OData filter string to apply to the report data. This field can be left empty if no filters are needed. | No |
Sample Request
This example requests an export of the "Available to Promise" report without any filters.
{ "reportTypeCode": "available_to_promise", "filter": "" }
Success Response
A successful request will return a 200 OK status and a JSON body containing the unique identifier for your export job. You must save this identifier to check the status in the next step.
{ "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }Step 2: Check Export Status and Download
After requesting the export, you must periodically check its status. This is known as "polling."
Endpoint:
GET /v3.1/Report/async-report/{identifier}
Replace {identifier} with the value you received in the response from Step 1.
Response Body
The response will contain the current status of your job.
Parameter | Type | Description |
| String | The unique ID of your export job. |
| String | The code of the report being generated. |
| String | The current status of the job. Possible values are |
| DateTime | The timestamp when the export was requested. |
| DateTime | The timestamp when the system started processing the job. |
| DateTime | The timestamp when the job was completed or failed. |
| Integer | The total time in seconds the job took to complete. |
| String | This field appears only when the |
| String | Provides details if the job has failed. |
Sample Responses
Status: Processing
The job is still running in the background. You should continue to poll this endpoint until the status changes.
{ "identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"reportTypeCode": "available_to_promise",
"statusCode": "Processing",
"requestDateTime": "2025-09-08T14:01:05.571Z",
"processingDateTime": "2025-09-08T14:01:05.571Z",
"completedDateTime": null,
"duration": 0,
"url": null,
"message": null }Status: Completed
The job is finished, and the report is ready. Use the value of the
url field to download the .xlsx file.
{ "identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"reportTypeCode": "available_to_promise",
"statusCode": "Completed",
"requestDateTime": "2025-09-08T14:01:05.571Z",
"processingDateTime": "2025-09-08T14:01:06.115Z",
"completedDateTime": "2025-09-08T14:02:15.845Z",
"duration": 70,
"url": "https://logiwa-report-exports.s3.amazonaws.com/your-report.xlsx?presigned-params...",
"message": "Success" }Supported Reports
Initially, this feature is available for the following report. More reports will be added in the future.
Report Name | reportTypeCode |
Available to Promise |
|
Validations and Error Handling
The system performs several validation checks to ensure requests are valid and to prevent redundant processing. Below are the common error scenarios you may encounter.
Initial Request Errors -> POST /v3.1/Report/async-report
These errors occur when you first request the report export.
Invalid Report or Filters
The system validates that the reportTypeCode exists and that the provided filters are applicable to that specific report. If the validation fails, the system will reject the request.
Duplicate Request
To prevent redundant processing, the system checks if an identical request from the same user is already in a Pending or Processing state. If an active duplicate is found, the new request is rejected.
Status Check Errors -> GET /v3.1/Report/async-report/{identifier}
This error occurs when you are polling for the status of an export job.
Job Not Found
If the identifier provided in the URL does not match any existing export job, the system will return an error.