Asynchronous Reporting API

Overview

We have asynchronous API endpoints to interact with your Extole reports. The three most essential endpoints can be used to run, check the status of, and download reports.

Generate an Access Token

To get started, you'll first need to get an access token. This will authorize you to make calls to our APIs. To generate a long-lived access token, follow our documentation on Generating Long-Lived Access Tokens.

Get a Report

Different reports require different parameters. To find out exactly how your API call should look, first go to Reports in My Extole and run the report. Once the report is running or complete, you have two options to get the correct API call.

Open the kebab menu to the right of the report listing and select the option to Get API Call.

Click into the report and and hit the button to Get API Call in the top right.

Both of the above methods will take you to the same page, where you can view and copy the GET call. This page also has the POST as well as the request body and response.

Get Scheduled Reports

For scheduled reports, the Get API Call button on the schedules page will give you the latest version of the scheduled report.

Successful GET Output

There are 2 endpoints that can be used for getting report information. /{report_id} and /{report_id}/download. The first of which will return a body similar to:

{
"report_id": "660227271228629029",
"name": "list_of_successful_advocates",
"executor_type": "spark",
"format": "JSON",
"status": "PENDING",
"user_id": "6458996259994687201",
"parameters": {
  "end_date": "2024-09-17",
  "client_id": "1990234113",
  "start_date": "2024-9-11"
  },
"visible": null,
"source": null,
"created_date": "2024-9-17T19:10:05.695Z",
"started_date": null,
"completed_Date": null,
"error_code": null,
"dounload_url": null
}

Which contains all of the information about the report.

The /{report_id}/download will allow you to download the contents of the report. For scheduled reports, you can always download the latest version of the report with /{report_id}/latest/download. The API call will return the contents of the report in the format specified by the extension:

File Type	Extension
.csv	Comma Separated Values
.headless_csv	CSV without header row
.psv	Pipe Separated Values
.headless_psv	PSV without header row
.xlsx	Excel File
.json	JSON
.jsonl	JSON Lines

Execute a Report

To run a report via API call, follow the instructions below.

Make a POST call to our reports endpoint.

POST <https://api.extole.io/v4/reports>

Include these HTTP Headers:

Authorization: <ACCESS_TOKEN>
Content-Type: application/json

Include this body with your values filled in:

{    
   "name":"<REPORT_NAME>",  
   "format":"<FORMAT>",  
   "parameters":{    
      "date_range":"<DATE_RANGE.START>/<DATE_RANGE.END>"  
   }  
}

Options for the parameters above:

Parameter	Value
<REPORT_NAME>	The name of the report you want to download.
	JSON, CSV
<DATE_RANGE.START>	Any start date for the report range in the format YYYY-MM-DD.
<DATE_RANGE.END>	Any end date for the report range in the format YYYY-MM-DD.

Check the Status of a Report

There are four options for the status of the report.

Pending: The report is preparing to run.
In progress: The report is initialized and in progress. Depending on the amount of data you pull back, reports typically remain in this status for one to ten minutes.
Failed: There was an error in the API call.
Done: The report is complete and ready to be downloaded.

To get a report's status, simply make the GET call listed on the report's Get API Call page and look for the status parameter in the response.

Download a Report

Once the status of a report is DONE you will be able to download your report. You can do so by making the following GET call.

GET https://api.extole.io/v4/reports/<REPORT_ID>/download