th:nth-child(2) {
    white-space: nowrap;
  }

# Grid API Exports

The grid API allows you to export data in multiple file formats in addition to the default JSON:

* **Excel (xlsx)**: Microsoft Excel spreadsheet
* **CSV**: Comma-separated values
* **TSV**: Tab-separated values


# Starting an Export

Getting an exported file from the Grid API is a three-step process:

1. Request the export
2. Wait for the export to finish
3. Download the exported file


## 1. Request the export

To request an export, send a `POST` request to the entity's endpoint URL with the `exports` suffix:

`https://api.observepoint.com/v3/reports/grid/<entity-type>/exports` ([API reference](/openapi/grid-api.openapi#tag/grid-data-export/operation/initiateGridDataExport))

The `POST` payload supports the same JSON as a normal Grid API request, with all the same columns, filters, sorting, pagination, and grouping.

Tip: pagination is not necessary with the exports API.

You can pass the `fileFormat` field to specify the exported file type. Supported values are found in the table below.

| File type | `fileFormat` value | What it is / when to use |
|  --- | --- | --- |
| Excel (XLSX) | `xlsx` | Standard spreadsheet format that works well with Excel and other spreadsheet tools. |
| CSV | `csv` | Plain text with comma separators. Highly compatible across tools. |
| TSV | `tsv` | Plain text with tab separators. Useful when data contains many commas. |


```javascript Example export request
{
  "columns": [
    {
      "columnId": "COLUMN_ID_1"
    },
    {
      "columnId": "COLUMN_ID_2"
    }
  ],
  "fileFormat": "csv" // choose: xlsx, csv, tsv
}
```

The API will respond with an `exportId` that you can use to track the export status.

```javascript Example export response
{
  "exportId": 123456
}
```

Your code will use the `exportId` value in the next step.

## 2. Wait for the export to finish

Exports can take a few seconds or a few minutes to complete, depending on the size of the exported file.

Poll for the exports API every 5-60 seconds until the export is complete:

`https://api.observepoint.com/v3/exports/?exportIds=<exportId>`

The API will respond with an array of one export object, like this:

```javascript Example export status response
{
  "exports": [
    {
      "exportId": 123456,
      "exportStatus": "in_progress", // poll until this changes to "completed"
      "exportType": "GRID_DATA_EXPORT",
      "exportDownloadLink": "https://api.observepoint.com/v3/exports/68c38841-e924-4cd0-a615-ef67d2bcf103"
    }
  ]
}
```

## 3. Download the exported file

Use the URL in `exportDownloadLink` to download the exported file. Following this URL will redirect you to the
actual download URL for the file.

The following example shows how to do this in Python:

```python Python export download example
import requests

# Get the export download link from the /v3/exports/?exportIds=123456 JSON response
export_download_link = exports_response_json["exports"][0]["exportDownloadLink"]

# Tip: the requests library will automatically follow the redirect
response = requests.get(export_download_link)
response.raise_for_status()

with open(f'/tmp/my-export.xlsx', 'wb') as f:
    for chunk in response.iter_content():
        if chunk:
            f.write(chunk)
```

Now the file is available on your local filesystem at the location of your choice.