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

Name

Type

Description

orgId

integer

The ID of the organisation for which you want to list exports

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

Name

Type

Description

exportId

integer

The ID of the export

orgId

integer

The ID of the organisation containing the export

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

Name

Type

Description

orgId

integer

The ID of the organisation

Request Body

Name	Type	Description
Body	string	the request payload

Name

Type

Description

Body

string

the request payload

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

Name

Type

Description

exportId

integer

The ID of the export

Request Body

Name Type Description

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

Body

object

Must be an empty JSON object : {}

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

Name

Type

Description

exportId

integer

The ID of the export

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

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

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.

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.

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

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

Name

Type

Description

executionId

string

The ID of the execution

organisationId

integer

The ID of the organisation

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

Name

Type

Description

executionId

string

The ID of the execution

organisationId

integer

The ID of the organisation

PreviousExporting your data NextDatamart replication

Last updated 3 years ago