Generating async reports

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

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

Today, Create billing report export is the first report that uses this pattern. Additional report types will reuse 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

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
  }'

Layer responds with 202 Accepted and an Export resource:

{
  "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.

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.

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.

Get started

Integration steps

API details

Generating async reports

Prerequisites

Workflow

Prefer webhooks instead of polling

​Prerequisites

​Workflow

​Prefer webhooks instead of polling

​Related endpoints

Prerequisites

Workflow

Prefer webhooks instead of polling

Related endpoints