> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/export-your-data/export.md).

# Export

Create an ndjson export from an OTQL query, run it, and download the result.

## Your goal

Get the result of an OTQL query out of the platform as a file - for an analyst, a partner, or a one-off need.

## Expected outcome

An `ndjson` file containing exactly the properties you selected in your query.

{% hint style="success" %}
For occasional exports, use the Navigator - **Data Studio > Exports** - rather than the API. The API exists to automate the process.
{% endhint %}

## The objects involved

An **export is a definition** with:

* a name,
* an output format - always `JSON` for now,
* a type - always `QUERY` for now,
* an associated query,
* an associated organisation,
* an associated datamart.

**Each export has executions**, representing its result at a given time.

```mermaid
stateDiagram-v2
    [*] --> Pending: execution generated
    Pending --> Running: export starts
    Running --> Succeeded: file produced
    Running --> Failed: error
```

The resulting file is formatted as [`ndjson`](http://ndjson.org) and contains the properties you selected in the `SELECT` part of the OTQL query.

## Run an export

{% stepper %}
{% step %}

### Write and save the query

Create the OTQL query the export is based on. See [OTQL](/setup-and-monitor/operate-and-monitor/query-your-datamart/otql.md).

{% hint style="warning" %}
**Check your query and verify its results before creating the export.** It is much easier at this stage: a query that returns nothing produces an empty file and **no message**.
{% endhint %}
{% endstep %}

{% step %}

### Create the export definition

```
POST https://api.mediarithmics.com/v1/exports?organisation_id=:orgId
```

```json
{
    "name": "<YOUR_EXPORT_NAME>",
    "output_format": "JSON",
    "query_id": "<ID_OF_THE_QUERY>",
    "type": "QUERY"
}
```

Definitions can be listed with `GET /v1/exports?organisation_id=:orgId` and read with `GET /v1/exports/:exportId?organisation_id=:orgId`.
{% endstep %}

{% step %}

### Generate an execution

```
POST https://api.mediarithmics.com/v1/exports/:exportId/executions
```

The body must be an empty JSON object: `{}`.
{% endstep %}

{% step %}

### Follow it

```
GET https://api.mediarithmics.com/v1/exports/:exportId/executions
```

Watch `status`, and once it succeeds, read `result.output_files` - it holds the technical name of the file to download, usually `export` when there is a single file.

`num_tasks`, `completed_tasks`, and `erroneous_tasks` tell you how much of the export succeeded.
{% endstep %}

{% step %}

### Download the file

Two methods, the exports API being the recommended one:

{% tabs %}
{% tab title="Exports API" %}

```
GET https://api.mediarithmics.com/v1/exports/:exportId/executions/:executionId/files/technical_name=:technicalName
```

`technical_name` is a value from `result.output_files`.

For a query such as `SELECT {emails {id}} FROM UserPoint WHERE segments {id="<SEGMENTID>"}`, the file looks like:

```json
{"emails":[{"id":"87987987985465432198"}]}
{"emails":[]}
{"emails":[]}
{"emails":[{"id":"46546549879879845654"},{"id":"564654987987465465465"}]}
```

Note the empty arrays: a UserPoint matching the query but with no email still produces a line.
{% endtab %}

{% tab title="Data file API" %}

```
GET https://api.mediarithmics.com/v1/data_file/data?uri=mics://data_file/tenants/:organisationId/jobs/executions/:executionId/result/export.data
```

{% endtab %}
{% endtabs %}

A `404` means the file does not exist or has been removed.
{% endstep %}
{% endstepper %}

## When an execution fails

Download the error file:

```
GET https://api.mediarithmics.com/v1/data_file/data?uri=mics://data_file/tenants/:organisationId/jobs/executions/:executionId/result/export.error
```

## Verify

* The query returns the expected results **before** you create the export.
* The execution reaches `Succeeded`, and `erroneous_tasks` is zero or explained.
* The downloaded file has the number of lines you expected, and the properties you selected.

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>OTQL</strong></td><td>Writing the query behind the export.</td><td><a href="/setup-and-monitor/operate-and-monitor/query-your-datamart/otql.md">OTQL</a></td></tr><tr><td><strong>File destination</strong></td><td>Delivering files to a partner instead of downloading them.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/export-your-data/file-destination.md">File destination</a></td></tr><tr><td><strong>Export your data</strong></td><td>Choosing between the export routes.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/export-your-data.md">Export your data</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/export-your-data/export.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.