Exports overview

How exports work

There are two ways to start an export:

• Use the API to trigger an operation you've configured in Maestra.
• Schedule a recurring export to FTP/SFTP. See Exports to FTP/SFTP.

Here's how it works:

1. Send an export request. You can pass selection criteria in the body to define what gets exported. You'll get back an export ID.
2. Check the status using that ID. Once the export is done, you'll get URLs to the result files.
3. Download the files and process the data.

Send an export request

Your request body can include:

• A segment ID
• A time range
• Connection details for an external storage destination
• Or nothing

The exact parameters depend on the operation. See the docs for the specific export operation you're using.

Request

POST https://api.maestra.io/v3/operations/sync?endpointId={endpointId}&operation={operation}
Accept: application/json
Content-Type: application/json
Authorization: SecretKey {Secret key}

{
    <Request body — see the operation's docs>
}

Successful response

{
  "status": "Success",
  "exportId": "<The export ID to pass in the next request>"
}

Duplicate request

If an identical export is already running, you'll see isDuplicate in the response. Use the check export status request to monitor its status.

{
  "status": "Success",
  "exportId": "<Export ID>",
  "isDuplicate": "<An export with the same settings is already running>"
}

Check export status

POST https://api.maestra.io/v3/operations/sync?endpointId={endpointId}&operation={operation}
Accept: application/json
Content-Type: application/json
Authorization: SecretKey {Secret key}

{
    "exportId": "<Export ID>"
}

Export status: Still processing

{
    "status": "Success",
    "exportResult": {
        "processingStatus": "NotReady"
    }
}

Export status: Ready to download

{
    "status": "Success",
    "exportResult": {
        "processingStatus": "Ready",
        "urls": [
            "<Result file URL>",
            "<Result file URL>",
            ...
        ]
    }
}

A few things to know about the files:

• Files stay available for 180 days.
• There's no cap on how much data you can export.
• Each file targets around 1 million rows, but individual files may be larger or smaller.
• There's no pagination ‚ all the data comes back as a set of files.
• Files are gzipped.
• The export format (XML, JSON, or CSV) is set when you configure the export operation.
• Files use UTF-8 encoding.

Export status: Cancelled

If an export gets cancelled, the status response tells you why and the job stops.

Content-Type: application/json; charset=utf-8

{
    "status": "Success",
    "exportResult": {
        "processingStatus": "Cancelled",
        "cancellationReason": "<Reason>"
    }
}

Exports can be cancelled for a few reasons:

• Someone cancelled the job from your Maestra workspace.
• An internal error occurred.
• The job hit internal resource limits. To get around this, simplify the segment filter or shorten the time range, then submit again.