---
updatedAt: 2026-10-05T12:55:32.000Z
agentTools:
  projectIndex: https://docs.validio.io/llms.txt
---

# CSV Export API

Export Validio data — sources, validators, incidents, activity, glossary terms and assignments, debug records, and sample data — as CSV via 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.

# Base URL

```text
https://YOUR-INSTALLATION.validio.io/api/export/v1/
```

# Authentication

The CSV Export endpoints use the same `Authorization` header as the [GraphQL API](https://docs.validio.io/docs/validio-api):

```text
Authorization: <access-key>:<access-secret>
```

Refer to [Managing API Keys](https://docs.validio.io/docs/managing-api-keys) for how to create credentials. 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

| Endpoint                                       | Permission                                |
| :--------------------------------------------- | :---------------------------------------- |
| `GET /api/export/v1/sources`                   | `SOURCES_READ`                            |
| `GET /api/export/v1/validators`                | `VALIDATORS_READ`                         |
| `GET /api/export/v1/incident-groups`           | `INCIDENTS_READ`                          |
| `GET /api/export/v1/activities`                | Scoped per activity type                  |
| `GET /api/export/v1/glossary-terms`            | `GLOSSARY_READ`                           |
| `GET /api/export/v1/glossary-term-assignments` | `GLOSSARY_READ`                           |
| `GET /api/export/v1/incident-debug-records`    | `INCIDENTS_WRITE` + `SQL_EXECUTION_WRITE` |
| `GET /api/export/v1/sample-data`               | `CATALOG_ASSETS_READ`                     |

# 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**. Narrow the time range or split a filter into multiple requests when you need more.

# Filters and sort

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

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

Both parameters use the same field shapes as the equivalent filter and sort inputs on the Validio UI; field names are documented per endpoint below.

The glossary endpoints do not accept `filter` or `sort`. They take an optional URL-encoded JSON array of term IDs instead — `ids` on `glossary-terms` and `termIds` on `glossary-term-assignments` — and export every term or assignment when it is omitted.

Example, exporting incident groups in the `production` namespace for March 2026:

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

curl "https://YOUR-INSTALLATION.validio.io/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
```

# Endpoint reference

## Sources

`GET /api/export/v1/sources`

| Column            | Description                                         |
| :---------------- | :-------------------------------------------------- |
| `ID`              | Source identifier.                                  |
| `Name`            | Display name.                                       |
| `Namespace`       | Namespace the source belongs to.                    |
| `Owner`           | Email of the source owner, if set.                  |
| `Tags`            | Comma-separated list of tag labels applied.         |
| `Credential type` | The credential type the source uses to connect.     |
| `Validator count` | Number of validators currently bound to the source. |
| `Created at`      | ISO-8601 timestamp.                                 |

## Validators

`GET /api/export/v1/validators`

| Column         | Description                                  |
| :------------- | :------------------------------------------- |
| `ID`           | Validator identifier.                        |
| `Name`         | Display name.                                |
| `Namespace`    | Namespace the validator belongs to.          |
| `Source`       | Name of the parent source.                   |
| `Segmentation` | Name of the segmentation (or `Unsegmented`). |
| `Window`       | Name of the window.                          |
| `Type`         | Validator type.                              |
| `Owner`        | Email of the validator owner, if set.        |
| `Tags`         | Comma-separated list of tag labels applied.  |
| `Created at`   | ISO-8601 timestamp.                          |

## Incident groups

`GET /api/export/v1/incident-groups`

| Column                  | Description                                              |
| :---------------------- | :------------------------------------------------------- |
| `ID`                    | Incident group identifier.                               |
| `Status`                | Group lifecycle status, e.g. `TRIAGE`, `RESOLVED`.       |
| `Priority`              | Group priority (`LOW`, `MEDIUM`, `HIGH`).                |
| `Owner`                 | Email of the group owner, if set.                        |
| `Source`                | Name of the related source.                              |
| `Validator`             | Name of the related validator.                           |
| `Validator Type`        | Validator type.                                          |
| `Namespace`             | Namespace the group belongs to.                          |
| `First Seen`            | Timestamp of the first incident in the group.            |
| `Last Seen`             | Timestamp of the most recent incident in the group.      |
| `Last End Time`         | End time of the most recent incident.                    |
| `Created At`            | When the group was created.                              |
| `Incident Count`        | Number of individual incidents in the group.             |
| `High Severity Count`   | Incident count at `HIGH` severity.                       |
| `Medium Severity Count` | Incident count at `MEDIUM` severity.                     |
| `Low Severity Count`    | Incident count at `LOW` severity.                        |
| `Muted Until`           | Timestamp until which the group is muted, if applicable. |

Filter accepts `range.start` and `range.end` to time-bound the export.

## Activities

`GET /api/export/v1/activities`

This endpoint backs the **Export** button on the activity logs in the UI; see [Activity Logs](https://docs.validio.io/docs/activity-logs) for the feature overview. Visibility is scoped per activity type by the permissions on your API key — for example, `SOURCES_READ` lets the export include source-related activity entries. Filter fields: `namespace`, `source`, `validator`, `timeRange`.

| Column          | Description                                                                 |
| :-------------- | :-------------------------------------------------------------------------- |
| `Timestamp`     | ISO-8601 UTC timestamp.                                                     |
| `Action`        | Action verb (`CREATED`, `UPDATED`, `DELETED`, or a resource-specific verb). |
| `Activity type` | Event type identifier.                                                      |
| `Entity name`   | Name of the affected resource at the time of the event.                     |
| `Entity ID`     | Identifier of the affected resource.                                        |
| `Actor type`    | `User`, `API key`, or `System`.                                             |
| `Actor`         | Email (for users) or API-key name (for API keys); empty for `System`.       |
| `Namespace`     | Namespace the resource belonged to, where applicable.                       |
| `Description`   | Human-readable summary of the event.                                        |

Activity rows for deleted resources stay in the export with their original name preserved, so records like "user X deleted source Y" remain visible after Y is removed.

## Glossary terms

`GET /api/export/v1/glossary-terms`

Exports your [Business Glossary](https://docs.validio.io/docs/business-glossary) term definitions. Pass an optional `ids` parameter — a URL-encoded JSON array of term IDs — to export selected terms only.

| Column            | Description                                                           |
| :---------------- | :-------------------------------------------------------------------- |
| `id`              | Glossary term identifier.                                             |
| `name`            | Term name.                                                            |
| `description`     | Free-text definition of the term.                                     |
| `aliases`         | Alternative names, comma-separated within the cell.                   |
| `domain`          | Name of the domain the term belongs to, if set.                       |
| `owner`           | Email of the term owner, or the user ID for owners without an email.  |
| `classifications` | Classifications applied to the term, comma-separated within the cell. |

These are the same headers the glossary CSV importer reads, so an exported file can be edited and uploaded back.

## Glossary term assignments

`GET /api/export/v1/glossary-term-assignments`

Exports every [glossary term assignment](https://docs.validio.io/docs/glossary-term-assignments) as one row, which is the file behind a critical data element register. Asset-level and field-level assignments share the same table: an asset-level row leaves `schemaFieldId` and `fieldPath` empty. Pass an optional `termIds` parameter — a URL-encoded JSON array of term IDs — to export the assignments of selected terms only.

| Column           | Description                                                                                                   |
| :--------------- | :------------------------------------------------------------------------------------------------------------ |
| `termId`         | Glossary term identifier.                                                                                     |
| `termName`       | Term name.                                                                                                    |
| `catalogAssetId` | Identifier of the catalog asset the term is assigned to.                                                      |
| `location`       | Dot-separated path of the catalog asset, for example `ANALYTICS.FINANCE.ORDERS`.                              |
| `schemaFieldId`  | Identifier of the schema field the term is assigned to. Empty on an asset-level assignment.                   |
| `fieldPath`      | Path of the assigned field within the asset, for example `/amount`. Empty on an asset-level assignment.       |
| `isPropagated`   | `true` for a term [propagated via lineage](https://docs.validio.io/docs/glossary-term-propagation), `false` for one assigned directly. |
| `assignedAt`     | ISO-8601 timestamp.                                                                                           |

## Incident debug records

`GET /api/export/v1/incident-debug-records?incidentId={id}`

Returns the rows produced by debugging the given incident. Columns are determined by the debug query at runtime — there is no fixed schema.

## Sample data

`GET /api/export/v1/sample-data?assetId={id}&credentialId={id}&query={sql}`

Returns the rows produced by running `query` against the catalog asset. Columns are determined by the query at runtime — there is no fixed schema.

# Scheduling

Export endpoints are stateless GET requests — schedule them with any tool that can call a URL with an `Authorization` header (cron, Airflow, GitHub Actions, your data orchestrator of choice). Pass time bounds in the `filter` querystring so 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/docs/segmentation-configuration#segment-usage-and-metric-retention). 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 a missed run does not lose data.
* Use overlapping ranges and dedupe on the `ID` column when stitching consecutive exports together.