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

# Data Exports

> Export large datasets as CSV or JSON files via the API.

Endpoints which return collections (e.g. `/projects`, `/events`) support async data exports via the `response_mode` query parameter. This lets you export full datasets without pagination limits.

## Response Modes

The `response_mode` query parameter controls the response format on any list endpoint:

| Value                 | Description                                                |
| --------------------- | ---------------------------------------------------------- |
| `default`             | Standard paginated response                                |
| `summary`             | Returns a `count` and 10 `samples`, no pagination          |
| `summary_with_export` | Returns a summary and triggers an async CSV or JSON export |

Here's an example query string: `/api/v1/projects?response_mode=summary_with_export`.

## Export Format

The `export_format` query parameter controls the file format when using `summary_with_export`:

| Value  | Description                      |
| ------ | -------------------------------- |
| `csv`  | Comma-separated values (default) |
| `json` | JSON array of objects            |

Here's an example: `/api/v1/projects?response_mode=summary_with_export&export_format=json`.

## Export Flow

When you request `response_mode=summary_with_export`, the response includes an `export` object:

<CodeGroup>
  ```json json theme={null}
  {
    "count": 42,
    "samples": [...],
    "response_mode": "summary_with_export",
    "export": {
      "id": "exp_ABC123",
      "status": "pending",
      "status_url": "https://app.gomangrove.com/api/v1/exports/exp_ABC123"
    }
  }
  ```
</CodeGroup>

Poll the `status_url` until `status` changes to `completed`. The response will then include a `download_url`:

<CodeGroup>
  ```json json theme={null}
  {
    "id": "exp_ABC123",
    "status": "completed",
    "download_url": "https://...",
    "file_size_bytes": 102400,
    "format": "csv"
  }
  ```
</CodeGroup>

The `download_url` is a temporary URL valid for 24 hours.

## Supported Endpoints

The list endpoints below can produce a file with `response_mode=summary_with_export`:

| Endpoint                        | Resource       |
| ------------------------------- | -------------- |
| `GET /projects`                 | Projects       |
| `GET /projects/:id/events`      | Events         |
| `GET /projects/:id/event_types` | Event Types    |
| `GET /projects/:id/data_points` | Data Points    |
| `GET /batches`                  | Batches        |
| `GET /ledgers`                  | Ledgers        |
| `GET /orders`                   | Orders         |
| `GET /feedstocks`               | Feedstocks     |
| `GET /tracking_units`           | Tracking Units |
| `GET /models`                   | Models         |
| `GET /reports`                  | Reports        |
| `GET /locations`                | Locations      |

<Note>
  This table is the **export-capable** set. `response_mode=summary` (count plus 10
  samples) works on more list endpoints than `summary_with_export`, which only
  produces a file for the resources on this list. Requesting an export on an
  unsupported endpoint returns a summary without a file.
</Note>

<Note>
  **Deliveries** are exportable by resource type (`POST /exports` with
  `resource_type: "Delivery"`), but there is no account-token `/deliveries` list
  endpoint, so `summary_with_export` is not reachable for deliveries via a list
  endpoint.
</Note>

<Note>
  Export creation is restricted to **account-level tokens**. Customer- and
  partner-scoped tokens receive a `403` when requesting `summary_with_export`.
</Note>

## Limits

* Max **5 concurrent exports** per account.
* Max **500 MB** file size per export.
* Download URLs expire after **24 hours**.
* Export records are cleaned up after **7 days**.