> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

Today, [Create billing report export](/api-reference/v1/create-billing-report-export) is the first report that uses this pattern. Additional report types will reuse the same [Exports](/api-reference/v1/list-exports) polling endpoints.

## Prerequisites

* An active Layer account and API credentials
* A valid access token (see [Initial Setup](/guides/initial-setup))
* Optional: a webhook endpoint configured to receive `export.completed` and `export.failed` (see [Webhooks](/api-details/webhooks))

## Workflow

<Steps>
  <Step title="Submit the report request">
    Call the report-specific creation endpoint. For billing reports:

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="Poll for status">
    Call [Fetch export](/api-reference/v1/fetch-export) until `status` is `completed` or `failed`:

    ```bash theme={null}
    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](/api-reference/v1/list-exports).
  </Step>

  <Step title="Download the file">
    When `status` is `completed`, download the artifact from `download_url`. The URL is a short-lived presigned link.

    ```bash theme={null}
    curl -L -o billing-report.xlsx "<download_url>"
    ```

    Use `file_name` from the export response when saving the file locally.
  </Step>
</Steps>

## 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:

```json theme={null}
{
  "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](/api-reference/v1/fetch-export) to retrieve the `download_url`.

See [Webhooks](/api-details/webhooks) for endpoint setup and signature verification, and the [Event Catalog](/api-details/webhooks-event-catalog) for the full list of event types.

## Related endpoints

* [Create billing report export](/api-reference/v1/create-billing-report-export)
* [List exports](/api-reference/v1/list-exports)
* [Fetch export](/api-reference/v1/fetch-export)