Generating async reports

Submit an export request, poll for status or use webhooks, then download the file

Some Layer reports are too large or expensive to generate in a single synchronous request. For those, Layer uses an async export workflow:

1. Submit a report generation request
2. Poll the export status (or wait for a webhook)
3. Download the completed file

Billing report exports and bookkeeping status report exports both use the same Exports polling endpoints.

Prerequisites

• An active Layer account and API credentials
• A valid access token (see Initial Setup)
• Optional: a webhook endpoint configured to receive export.completed and export.failed (see Webhooks)

Workflow

1. Submit the report request

   Call the report-specific creation endpoint. For billing reports:

   curl -X POST https://sandbox.layerfi.com/v1/billing/reports \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
       "end_month": 6,
       "end_year": 2026
     }'
   

   For a client-wide bookkeeping status XLSX instead, send a JSON body to Create bookkeeping status report export. An empty object uses the default report options:

   curl -X POST https://sandbox.layerfi.com/v1/reports/bookkeeping/exports \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{}'
   

   Layer responds with 202 Accepted and an Export resource (billing example below; the bookkeeping report uses export_type: bookkeeping_status_report):

   {
     "data": {
       "type": "Export",
       "id": "00000000-0000-0000-0000-000000000006",
       "business_id": null,
       "export_type": "billing_report",
       "status": "pending",
       "params": {
         "end_month": 6,
         "end_year": 2026
       },
       "download_url": null,
       "file_name": null,
       "error": null,
       "created_at": "2026-08-04T14:00:00-04:00",
       "started_at": null,
       "completed_at": null,
       "failed_at": null
     }
   }
   

   Save the export id. You will use it to poll for completion.

2. Poll for status

   Call Fetch export until status is completed or failed:

   curl https://sandbox.layerfi.com/v1/exports/{export_id} \
     -H "Authorization: Bearer <access_token>"
   

   Status values:

   Status	Meaning
   pending	Request accepted; generation has not started
   processing	Generation is in progress
   completed	File is ready; download_url is populated
   failed	Generation failed; see error

   You can also list recent exports with List exports, filtering by export_type (for example, bookkeeping_status_report).

3. Download the file

   When status is completed, download the artifact from download_url. The URL is a short-lived presigned link.

   curl -L -o billing-report.xlsx "<download_url>"
   

   Use file_name from the export response when saving the file locally.

Prefer webhooks instead of polling

If you do not want to poll, subscribe to export lifecycle webhooks in the Layer developer portal:

• export.completed — the export finished successfully
• export.failed — the export failed

These events are client-scoped: the payload includes id, type, and data, and does not include top-level business_id / business_external_id fields used by business-scoped webhooks.

Example export.completed payload:

{
  "id": "export_completed_00000000-0000-0000-0000-000000000006",
  "type": "export.completed",
  "data": {
    "export_id": "00000000-0000-0000-0000-000000000006",
    "business_id": null,
    "export_type": "billing_report",
    "status": "completed",
    "error": null
  }
}

After receiving export.completed, call Fetch export to retrieve the download_url.

See Webhooks for endpoint setup and signature verification, and the Event Catalog for the full list of event types.

Related endpoints

• Create billing report export
• Create bookkeeping status report export
• List exports
• Fetch export