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

# CSV Export API Overview

> Export Validio data (sources, validators, incidents, activity, glossary terms, debug records, and sample data) as CSV through REST endpoints for reporting, archival, and BI integration.

The CSV Export API exposes REST endpoints under `/api/export/v1/` that return Validio data as `text/csv`, for reporting, archival, and ingestion into BI tools or data warehouses. The same endpoints back the **Export** buttons in the Validio UI. The API is read-only; to create or change resources, use the [GraphQL API](https://docs.validio.io/v10.3/developer/validio-api.md).

## Base URL

```text title="Text" theme={null}
https://your-validio-instance/api/export/v1/
```

## Authentication

The CSV Export endpoints use the same `Authorization` header as the GraphQL API:

```text title="Text" theme={null}
Authorization: <access-key>:<access-secret>
```

For how to create an API key, see [Authentication](https://docs.validio.io/v10.3/developer/getting-started/authentication.md). The API key needs the same per-resource permission you would need in the UI, for example `SOURCES_READ` to export sources, or `INCIDENTS_READ` to export incident groups.

## Endpoints

Each endpoint has its own reference page, with its parameters and the columns it returns.

| Endpoint | Permission |
| :- | :- |
| [`GET /sources`](https://docs.validio.io/v10.3/developer/validio-api/csv-export-api/export-sources) | `SOURCES_READ` |
| [`GET /validators`](https://docs.validio.io/v10.3/developer/validio-api/csv-export-api/export-validators) | `VALIDATORS_READ` |
| [`GET /incident-groups`](https://docs.validio.io/v10.3/developer/validio-api/csv-export-api/export-incident-groups) | `INCIDENTS_READ` |
| [`GET /activities`](https://docs.validio.io/v10.3/developer/validio-api/csv-export-api/export-activity-logs) | Scoped per activity type |
| [`GET /glossary-terms`](https://docs.validio.io/v10.3/developer/validio-api/csv-export-api/export-glossary-terms) | `GLOSSARY_READ` |
| [`GET /incident-debug-records`](https://docs.validio.io/v10.3/developer/validio-api/csv-export-api/export-incident-debug-records) | `INCIDENTS_WRITE` and `SQL_EXECUTION_WRITE` |
| [`GET /sample-data`](https://docs.validio.io/v10.3/developer/validio-api/csv-export-api/export-sample-data) | `CATALOG_ASSETS_READ`, and `SQL_EXECUTION_WRITE` in the credential's namespace |

## Response format

Each response is a CSV download with a header row followed by data rows. The `Content-Disposition` filename includes the resource, an optional entity name, and the time range (or today's date if the request has no time bounds), for example `incident-groups-2026-03-01_2026-04-01.csv`.

Responses are capped at **100,000 rows**. When you need more, narrow the time range or split a filter into multiple requests.

## Filters and sort

The list endpoints (`sources`, `validators`, and `incident-groups`) accept two URL-encoded JSON query parameters:

* `filter` narrows the rows.
* `sort` orders the rows.

Both parameters use the same field shapes as the equivalent filter and sort inputs in the Validio UI. The `activities` endpoint accepts `filter` only, with the fields `namespace`, `source`, `validator`, and `timeRange`. Each endpoint's reference page describes its parameters.

A malformed `filter` or `sort` returns `400`, with a JSON body naming the problem.

The `glossary-terms` endpoint doesn't accept `filter` or `sort`. Instead, it takes an optional URL-encoded JSON array of term IDs (`ids`), and exports every term when it's omitted.

This example exports incident groups in the `production` namespace for March 2026:

```bash title="Bash" theme={null}
FILTER='{"namespace":["production"],"range":{"start":"2026-03-01T00:00:00Z","end":"2026-04-01T00:00:00Z"}}'

curl "https://your-validio-instance/api/export/v1/incident-groups?filter=$(printf '%s' "$FILTER" | jq -rR @uri)" \
  -H "Authorization: $VALIDIO_ACCESS_KEY:$VALIDIO_SECRET_ACCESS_KEY" \
  -o incident-groups-march.csv
```

## Scheduling

The export endpoints are stateless `GET` requests, so you can schedule them with any tool that can call a URL with an `Authorization` header, such as cron, Airflow, GitHub Actions, or your data orchestrator of choice. Pass time bounds in the `filter` query parameter so that each run downloads only the new rows.

## Retention

Validio retains incident, activity, and metric history for a finite window. For metrics, the window depends on the validator's window size and segment usage. See [Segment Usage and Metric Retention](https://docs.validio.io/v10.3/docs/segmentation/metric-retention.md). To preserve data beyond that window:

* Schedule exports more frequently than the retention boundary. If retention is 90 days, run the export at least weekly with a 30-day rolling window, so that a missed run doesn't lose data.
* Use overlapping ranges, and deduplicate on the `ID` column when you stitch consecutive exports together.