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

# Generate branded reports

> Estimate, enqueue, and retrieve an asynchronous AstroM8 report.

Premium report operations can return a PDF immediately or run asynchronously. For production integrations, use asynchronous mode so your request path stays short and observable.

## 1. Estimate the capability

```bash theme={null}
curl --request POST \
  --url 'https://api.astrom8.com/api/v3/estimates' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: astrom8_live_...' \
  --data '{"capability":"western.natal-premium-pdf"}'
```

## 2. Enqueue a report

Set `async` to `true`. Send an idempotency key from your system when a user action may be retried.

```bash theme={null}
curl --request POST \
  --url 'https://api.astrom8.com/api/v3/reports/natal-premium/pdf' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: astrom8_live_...' \
  --header 'Idempotency-Key: report-order-8f3c' \
  --data '{
    "birth_subject": {
      "birth_date": "1992-04-15",
      "birth_time": "09:30",
      "latitude": 13.7563,
      "longitude": 100.5018,
      "timezoneOffsetMinutes": 420
    },
    "locale": "en",
    "async": true
  }'
```

A `202` response includes `job_id` and a polling path. Credits are debited when a job is accepted; a terminal generation failure is refunded automatically.

## 3. Poll for completion

```bash theme={null}
curl --request GET \
  --url 'https://api.astrom8.com/api/v3/jobs/job_a1b2c3d4e5f60718293a4b5c' \
  --header 'X-API-Key: astrom8_live_...'
```

When `status` becomes `succeeded`, use `result.url` before its signed expiry. Do not persist a signed URL as a permanent asset reference. When `status` is `failed`, inspect the safe `error_code`; the response also states refunded credits where applicable.

## White-label fields

Report endpoints support request-level branding where the endpoint schema exposes `branding`. Reuse the same branding object from your application and keep logo URLs publicly reachable by the report renderer.