Query Exports

The platform allows you to export data as ndjson, based on OTQL queries. This action is available in the navigator or through API to automate the process.

For punctual exports, you may want to use the navigator (in Data Studio > Exports) rather than our API for more simplicity.

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.

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, and contains the properties you selected in the SELECT part of the OTQL query.

Listing exports

GET 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

200

{
    "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
}

Details of an export

GET 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

200

{
    "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"
    }
}

Create an export

You will first need to create a query for your export.

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.

Create an export

POST 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

200

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

// 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

POST 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 : {}

200

{
    "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"
    }
}

Execution status

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

Path Parameters

Name	Type	Description
exportId	integer	The ID of the export

200

{
    "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
}

If available, the technical name of the file to download is in the result.output_files array

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

GET 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.

200

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

404 The file does not exist or has been removed

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

Download using the data_file API

GET 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

200

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

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

200