BulkExport API Overview

How BulkExport works

There are four parts to BulkExport:

• A configuration that allows customers of Twilio Edition products to set automatic exports for each day.
• A way to export a specified day’s traffic.
• A means to manage exports in progress.
• A list of exported days with their output files.

ExportConfiguration

The ExportConfiguration resource lets you specify if you have a Twilio Editions product, whether exports will take place automatically every day. This makes getting the data much more simple: you just configure the webhook. This will be called when the day’s file is available, and you can then download and process your data.

Custom Jobs

Jobs lets you choose a range of dates to export data for. One data file will be generated for each day in the range. A parent account and all associated sub accounts can request data for up to a total of 366 days within a UTC calendar day. If making a request from a sub account, the parent account will be used to determine the amount of days being requested within a UTC calendar day. For instance, if you submit requests across several sub-accounts, and the aggregate number of requested days exceeds 366 within a 24-hour period, your request will be rejected. In this instance, you'll need to wait until the next UTC calendar day to make any further requests. The result data for the requested days will be visible using the Day resource. You will receive a callback and/or email for each job that completes. When a custom job completes, it will generate one Day resource for each day in the requested time period.

By default, the system will send bulk export job initiation notifications to account Owners and Admins, so they can keep a tab on the export requests, and flag/delete unwanted requests. Admins will be able to unsubscribe to these notifications from the notification center on the console.

Jobs

Get a list of jobs in progress or which have recently completed. Completed jobs will appear on the job list for seven days. You can delete jobs before they are complete.

Exported days

The Days resource lets you examine the list of exported days available, either because they have been already generated by an export job or an automatic daily export. Each day file is named with the ISO 8601 date, and days are listed in order of generation.

There is no way to delete completed Day files, but they will be deleted automatically seven days after their creation.

Subresources

Using BulkExport

There are two ways to use BulkExport:

1. If you have the Twilio Enterprise Edition, you can enable the daily export using the ExportConfiguration resource. This will generate one data file per day for every resource enabled. The system typically tries to create a data file based on the state of the data at that point, but may be delayed occasionally.
2. Create custom jobs using the ExportCustomJob resource.

You can then use the Day resource to list all completed exports by day and to download the message data for any of those days.

Messages BulkExport file format

Day files are stored and returned as compressed (Gzip) JSON files with one record per line. Records are similar to the Message resource. The differences are:

• Timestamps are in UTC in ISO 8601 format.
• Price data may not be present in every message in BulkExport.
• The following fields are not present:
  • price_units
  • api_version
  • error_message (but error_code is)
  • uri
  • subresource_uris (containing the media URLs)

Calls BulkExport file format

Day files are stored and returned as compressed (Gzip) JSON files with one record per line. Records are similar to the Calls resource. The differences are:

• Timestamps are in UTC in ISO 8601 format.
• Price data may not be present in every message in BulkExport.
• The following fields are not present:
  
  • uri
  • subresource_uris

Conferences BulkExport file format

Day files are stored and returned as compressed (Gzip) JSON files with one record per line. Records are similar to the Conferences resource. The differences are:

• Timestamps are in UTC in ISO 8601 format.
• The following fields are not present:
  • api_version
  • uri
  • subresource_uris

Participants BulkExport file format

Day files are stored and returned as compressed (Gzip) JSON files with one record per line. Records are similar to the Participants resource. The differences are:

• Timestamps are in UTC in ISO 8601 format.
• The following fields are not present:
  • uri
  • label