# Get loyalty points export status

Check whether an export has completed and read its row count and file size.

- Endpoint: `GET https://api.returning.ai/v1/loyalty-exports/{exportId}`
- Section: Gamification / Loyalty points
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `customerSuccess` (Shown in the dashboard as Customer Success.)
- Retries: Read-only; poll with a growing delay.
- Guide: hand-written
- Verified: live, 2026-10-12
- Last updated: 12 Oct 2026
- Web page: https://docs.returning.ai/api-reference/gamification-loyalty-points/get-loyalty-points-export-status

## When to use this

- Poll after requesting an export.
- Check whether a failed or expired report needs a new request.

**Instead:** Use [Get loyalty points export download link](https://docs.returning.ai/api-reference/gamification-loyalty-points/get-loyalty-points-export-download-link.md) once the job is completed.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `customerSuccess`

Use a Community API key with `customerSuccess`, shown as Customer Success in the dashboard. Keep the key on your backend and send `Authorization: Bearer <API_KEY>`. The key selects the community; do not send a community ID. Personal API keys are not supported.

All three calls use `https://api.returning.ai` and return `Cache-Control: no-store`. They accept no query parameters. A valid community key with the required permission can read that community's export jobs, including jobs created by another key in the same community.

Successful responses contain `meta`, `message` and `data`. Read job state from `data.status`. An HTTP `200` means the status request succeeded, even when the job is `failed`. Errors put their machine-readable code in `meta.code`; do not branch on `message`.

## Behaviour

| `data.status` | What to do |
| --- | --- |
| `queued` | Wait for processing. |
| `processing` | Continue polling with backoff. |
| `completed` | Read `total_rows` and `file_size_bytes`, then request a download link. |
| `failed` | Read `data.error`. Contact support or correct the cause before deliberately creating another job. |
| `cancelled` | No file is available. There is no public cancellation endpoint in this family. |
| `expired` | Create a new export if you still need the file. |

### Polling and recovery

Poll one known ID with increasing delays rather than creating another export. A client may choose a time budget and resume later using the saved ID. Reaching your own time budget does not cancel the job.

| Situation | Action |
| --- | --- |
| Still `queued` or `processing` | Wait and poll with backoff. If unusually long, contact support with the export ID and `meta.requestId`. |
| HTTP 200 with `failed` | The status lookup succeeded, but the export failed. Read `data.error`; investigate the input or contact support before deliberately requesting a new job. |
| `cancelled` | Stop polling; this family provides no public cancel or restart operation. |
| `expired` | Start a deliberately new export if the file is still needed. Replaying the original create does not refresh it. |
| HTTP 404 | Check the saved ID and the key's community. A malformed ID and an inaccessible ID both use `EXPORT_NOT_FOUND`. |
| HTTP 401 or 403 | Correct the Community API key or its Customer Success permission before retrying. |
| Network error or HTTP 5xx | Retry the same GET with backoff. Do not create a replacement export merely because a status read failed. |

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `exportId` | `string` | Yes | Export ID returned by Create loyalty points export. (24 hex characters) |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with Customer Success permission. The key selects the community. (Bearer <API_KEY>) |

### Example request

```bash
curl --request GET \
  --url https://api.returning.ai/v1/loyalty-exports/66f000000000000000000701 \
  --header 'Authorization: Bearer <API_KEY>'
```

## Response

`export_id`, `status`, `dataset`, `format`, `created_at` and `coverage` are always present. Only completed jobs include `total_rows` and `file_size_bytes`. A failed job adds `error: {"code":"EXPORT_FAILED","message":"The export could not be completed."}`. Other states omit these optional fields.

A completed empty export has `total_rows: 0`, a header-only CSV or an empty JSON array. It is not a list of customers with zero balances. No progress percentage, checksum, expiry timestamp, original filters or detailed failure reason is returned by this status endpoint.

Unknown IDs, malformed IDs and exports outside the authenticated community return `404 EXPORT_NOT_FOUND`. Failed and expired jobs that still exist return HTTP `200` with their job state.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `meta` | `object` | always | Request result and support reference. |
| `meta.status` | `string` | always | Result of the request. (success) |
| `meta.statusCode` | `integer` | always | HTTP status of the request. |
| `meta.requestId` | `string` | always | Support reference for this request. |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |
| `data` | `object` | always | Export job details. |
| `data.export_id` | `string` | always | Save this ID for status and download requests. |
| `data.status` | `string` | always | Current job state. Acceptance does not mean the file is ready. (queued, processing, completed, failed, cancelled or expired) |
| `data.dataset` | `string` | always | The dataset requested. (points_transactions) |
| `data.format` | `string` | always | The requested file format. (csv or json) |
| `data.created_at` | `string` | always | Job creation timestamp in UTC. |
| `data.coverage` | `string` | always | Recorded history only, not certified financial completeness. (observed_history_only) |
| `data.total_rows` | `integer` | completed only | File row count; zero for an empty report. Present only when completed. |
| `data.file_size_bytes` | `integer` | completed only | File size in bytes. Present only when completed. |
| `data.error` | `object` | failed only | Generic failure details. Present only for a failed job. |
| `data.error.code` | `string` | - | - |

### Example response (200)

```json
{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "requestId": "example-request"
  },
  "message": "Loyalty export status success.",
  "data": {
    "export_id": "66f000000000000000000701",
    "status": "completed",
    "dataset": "points_transactions",
    "format": "csv",
    "created_at": "2026-09-03T01:00:00.000Z",
    "coverage": "observed_history_only",
    "total_rows": 4,
    "file_size_bytes": 640
  }
}
```

## Errors

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Remove unsupported query parameters and correct the request fields. |
| 401 | `AUTHENTICATION_REQUIRED` | Send a valid Community API key in Authorization: Bearer <API_KEY>. |
| 403 | `API_KEY_PERMISSION_DENIED` | Use a Community API key with Customer Success permission. |
| 403 | `COMMUNITY_ACCESS_DENIED` | Use a Community API key, not a personal API key. |
| 400 | - | Invalid request or unsupported query parameters. |
| 401 | - | Missing or invalid API key. |
| 403 | - | A Community API key with the required permission is needed. |

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 404 | `COMMUNITY_NOT_FOUND` | Contact support about the community selected by your API key. |
| 404 | `EXPORT_NOT_FOUND` | Check the export ID and the community selected by your API key. |
| 404 | - | The export was not found. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 503 | `EXPORTS_UNAVAILABLE` | Retry with backoff. For create, preserve the original body and idempotency key. |
| 500 | `AUTHENTICATION_FAILED` | Retry with backoff; contact support if authentication checks keep failing. |
| 503 | - | Exports disabled or unavailable. Retry creation with the same idempotency key. |

**Retries:** This read-only call is safe to repeat. Poll with a growing delay, for example 5, 10, then 30 seconds. These are client guidance, not a completion-time guarantee or response fields. Stop polling at a terminal state. Retry network errors and 5xx responses with backoff.

## Next step

- [Get loyalty points export download link](https://docs.returning.ai/api-reference/gamification-loyalty-points/get-loyalty-points-export-download-link.md): `GET /v1/loyalty-exports/{exportId}/download`. For completed jobs, request a temporary download link.
- [Create loyalty points export](https://docs.returning.ai/api-reference/gamification-loyalty-points/create-loyalty-points-export.md): `POST /v1/loyalty-exports`. For an expired file, deliberately request a new export.