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

# Billing Export

> Export billable events to S3 and fetch export URLs

## Export Billing Data

Start a new export of billable events or poll the result of a previously started export.

### Endpoint

```
POST /external/v1/external_billing_data_export
```

### Authentication

> \[!NOTE]
> Requires a valid company API key in the `Authorization` header (format: `Api-Key <key>`).

### Usage

* **Start export**: Send `company_ids`, `start_date`, `end_date`, and optional `services`
* **Poll export**: Send only `tracker_id`

### Request Body

| Field         | Type                    | Required    | Description                                                                                    |
| ------------- | ----------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| `tracker_id`  | string (UUID)           | No          | If provided, returns the exported data for this tracker. No other fields required in this mode |
| `company_ids` | array of strings (UUID) | Conditional | List of company IDs. Required when starting a new export                                       |
| `start_date`  | string (date)           | Conditional | Start date (inclusive) in `YYYY-MM-DD` or ISO 8601 format. Required when starting a new export |
| `end_date`    | string (date)           | Conditional | End date (inclusive) in `YYYY-MM-DD` or ISO 8601 format. Required when starting a new export   |
| `services`    | array of strings        | No          | Optional list of billable event service names to filter by                                     |

### Available Services

`ApplicationStageTransition`, `DocumentAgent`, `BrowserAgent`, `LMS`, and more.

### Example Request - Start Export

```bash theme={null}
curl -X POST "https://api.firstwork.com/external/v1/external_billing_data_export" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_ids": ["company-uuid-1", "company-uuid-2"],
    "start_date": "2025-06-01",
    "end_date": "2025-10-31",
    "services": ["ApplicationStageTransition", "DocumentAgent"]
  }'
```

### Example Request - Poll Export

```bash theme={null}
curl -X POST "https://api.firstwork.com/external/v1/external_billing_data_export" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tracker_id": "tracker-uuid"
  }'
```

### Responses

#### 200: OK

Export complete. Returns export URLs.

#### 202: Accepted

Export started. Use the returned `tracker_id` to poll for results.

#### 400: Bad Request

Missing required fields or invalid date format.

#### 404: Not Found

Tracker ID not found.

#### 500: Internal Server Error

Unexpected error during export.

### Notes

* Dates are interpreted in the company's local timezone (midnight of `start_date` to 23:59:59 of `end_date`)
* Use the two-step flow: start the export, then poll with `tracker_id` until the result is ready