# Query Exports

The platform allows you to export data as `ndjson`, based on [OTQL queries](/querying-your-data/otql-queries.md). This action is available in the navigator or through API to automate the process.

{% hint style="success" %}
For punctual exports, you may want to use the navigator (in Data Studio > Exports) rather than our API for more simplicity.
{% endhint %}

**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](/communities-and-organisations.md)
* an associated [datamart](/communities-and-organisations/datamart.md)

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

An execution goes through different stages:

* `Pending` if the export is not started
* `Running` if the export is started
* `Succeeded` or `Failed` once the export has been completed

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

## Listing exports

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/exports?organisation_id=:orgId`

#### Path Parameters

| Name  | Type    | Description                                                   |
| ----- | ------- | ------------------------------------------------------------- |
| orgId | integer | The ID of the organisation for which you want to list exports |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok",
    "data": [
        {
            "type": "QUERY",
            "id": "9879",
            "organisation_id": "1426",
            "name": "2018-08-29 - Export test segments for Facebook and Adwords",
            "query_id": "65987",
            "datamart_id": "1509",
            "output_format": "JSON"
        },
        {
            "type": "QUERY",
            "id": "9872",
            "organisation_id": "1426",
            "name": "export-visiteurs",
            "query_id": "45987",
            "datamart_id": "1509",
            "output_format": "JSON"
        },
       ...
    ],
    "count": 50,
    "total": 163,
    "first_result": 0,
    "max_result": 50,
    "max_results": 50
}
```

{% endtab %}
{% endtabs %}

## Details of an export

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/exports/:exportId?organisation_id=:orgId`

#### Path Parameters

| Name     | Type    | Description                                      |
| -------- | ------- | ------------------------------------------------ |
| exportId | integer | The ID of the export                             |
| orgId    | integer | The ID of the organisation containing the export |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok",
    "data": {
        "type": "QUERY",
        "id": "8978",
        "organisation_id": "1426",
        "name": "2018-08-29 - Export test segments for Facebook and Adwords",
        "query_id": "98798",
        "datamart_id": "1509",
        "output_format": "JSON"
    }
}
```

{% endtab %}
{% endtabs %}

## Create an export

You will first need to [create a query for your export](/querying-your-data/otql-queries.md#creating-a-query).

{% hint style="info" %}
You should check your query and verify its results before creating an export. It is easier to do at this step, as the export would only return an empty file and no message.
{% endhint %}

## Create an export

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/exports?organisation_id=:orgId`

#### Path Parameters

| Name  | Type    | Description                |
| ----- | ------- | -------------------------- |
| orgId | integer | The ID of the organisation |

#### Request Body

| Name | Type   | Description         |
| ---- | ------ | ------------------- |
| Body | string | the request payload |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status":"ok",
    "data":
        {
          "type": "QUERY",
          "id": "8205",
          "organisation_id": "1426",
          "name": "test",
          "query_id": "50409",
          "datamart_id": "1509",
          "output_format": "JSON"
        }
}
```

{% endtab %}
{% endtabs %}

```javascript
// Creating an export payload
{
    "name": "<YOUR_EXPORT_NAME>",
    "output_format": "JSON",
    "query_id": "<ID_OF_QUERY_CREATED_IN_PREVIOUS_STEP>",
    "type": "QUERY"
}
```

## Generate an execution

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/exports/:exportId/executions`

#### Path Parameters

| Name     | Type    | Description          |
| -------- | ------- | -------------------- |
| exportId | integer | The ID of the export |

#### Request Body

| Name | Type   | Description                         |
| ---- | ------ | ----------------------------------- |
| Body | object | Must be an empty JSON object : `{}` |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok",
    "data": {
        "parameters": {},
        "organisation_id": "1426",
        "user_id": "2886",
        "result": null,
        "error": null,
        "id": "879879879",
        "status": "PENDING",
        "creation_date": 1612789702668,
        "start_date": null,
        "duration": null,
        "cancel_status": null,
        "debug": null,
        "is_retryable": false,
        "permalink_uri": "MTowOjA65985NjYyOQ==",
        "num_tasks": null,
        "completed_tasks": null,
        "erroneous_tasks": null,
        "retry_count": 0,
        "job_type": "DATAMART_QUERY_EXPORT"
    }
}
```

{% endtab %}
{% endtabs %}

## Execution status

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/exports/:exportId/executions`

#### Path Parameters

| Name     | Type    | Description          |
| -------- | ------- | -------------------- |
| exportId | integer | The ID of the export |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok",
    "data": [
        {
            "parameters": {},
            "organisation_id": "1426",
            "user_id": "8987",
            "result": {
                "output_files": [
                    "export"
                ]
            },
            "error": null,
            "id": "7897897",
            "status": "SUCCEEDED",
            "creation_date": 1562595783663,
            "start_date": 1562595789171,
            "duration": 292617,
            "cancel_status": null,
            "debug": null,
            "is_retryable": false,
            "permalink_uri": "",
            "num_tasks": 299808,
            "completed_tasks": 277105,
            "erroneous_tasks": 22703,
            "retry_count": 0,
            "job_type": "DATAMART_QUERY_EXPORT",
            "end_date": 1562596081788
        },
        {
            "parameters": {},
            "organisation_id": "1426",
            "user_id": "8987",
            "result": {
                "output_files": [
                    "export"
                ]
            },
            "error": null,
            "id": "9879879",
            "status": "SUCCEEDED",
            "creation_date": 1561655188369,
            "start_date": 1561655192158,
            "duration": 413140,
            "cancel_status": null,
            "debug": null,
            "is_retryable": false,
            "permalink_uri": "",
            "num_tasks": 284602,
            "completed_tasks": 263822,
            "erroneous_tasks": 20780,
            "retry_count": 0,
            "job_type": "DATAMART_QUERY_EXPORT",
            "end_date": 1561655605298
        },
        {
            "parameters": {},
            "organisation_id": "1426",
            "user_id": "9879",
            "result": {
                "output_files": [
                    "export"
                ]
            },
            "error": null,
            "id": "4564564",
            "status": "SUCCEEDED",
            "creation_date": 1535555844642,
            "start_date": 1535555850435,
            "duration": 337507,
            "cancel_status": null,
            "debug": null,
            "is_retryable": false,
            "permalink_uri": "",
            "num_tasks": null,
            "completed_tasks": null,
            "erroneous_tasks": null,
            "retry_count": 0,
            "job_type": "DATAMART_QUERY_EXPORT",
            "end_date": 1535556187942
        }
    ],
    "count": 3,
    "total": 3,
    "first_result": 0,
    "max_result": 10,
    "max_results": 10
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
If available, the technical name of the file to download is in the `result.output_files` array
{% endhint %}

## Download the result of an export

The result of an export is saved as a data file in the platform.

You have two methods to retrieve it :

* Using the exports API (recommended)
* Using the data\_file API

## Download using the exports API

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/exports/:exportId/executions/:executionId/files/technical_name=:technicalName`

#### Path Parameters

| Name        | Type    | Description                                              |
| ----------- | ------- | -------------------------------------------------------- |
| exportId    | integer | The ID of the export                                     |
| executionId | integer | The ID of the execution for which to download the report |

#### Query Parameters

| Name            | Type   | Description                                                                                                          |
| --------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| technical\_name | string | The name of the file(s) in the `result.output_files` of the execution. Usually `export` when there is a single file. |

{% tabs %}
{% tab title="200 " %}

```javascript
// For query SELECT {emails {id}} FROM UserPoint WHERE segments {id="<SEGMENTID>"}
{"emails":[{"id":"87987987985465432198"}]}
{"emails":[]}
{"emails":[]}
{"emails":[{"id":"46546549879879845654"},{"id":"564654987987465465465"}]}
```

{% endtab %}

{% tab title="404 The file does not exist or has been removed" %}

```javascript
{
    "status": "error",
    "error": "Resource Not Found",
    "error_id": "9eedef5f-dfe3-4354-9a2f-d79760113386"
}
```

{% endtab %}
{% endtabs %}

## Download using the data\_file API

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/data_file/data?uri=mics://data_file/tenants/:organisationId/jobs/executions/:executionId/result/export.data`

#### Query Parameters

| Name           | Type    | Description                |
| -------------- | ------- | -------------------------- |
| executionId    | string  | The ID of the execution    |
| organisationId | integer | The ID of the organisation |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Download the error file

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/data_file/data?uri=mics://data_file/tenants/:organisationId/jobs/executions/:executionId/result/export.error`

Use this endpoint in case of a `FAILED` execution status.

#### Query Parameters

| Name           | Type    | Description                |
| -------------- | ------- | -------------------------- |
| executionId    | string  | The ID of the execution    |
| organisationId | integer | The ID of the organisation |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.mediarithmics.io/data-streams/exporting-your-data/query-exports.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.