Skip to contentSkip to navigationSkip to topbar
On this page

BulkExport API Overview


(warning)

Warning

This feature is not currently available when using Twilio Regions Ireland (IE1) or Australia (AU1). It is currently only supported with the default US1 region. A full list of unsupported products and features with Twilio Regions is documented in the Global Infrastructure docs.

The BulkExport API provides an efficient mechanism for retrieving all of your activity logs from the Twilio platform on an ongoing basis, or for one-off downloads. Using BulkExport, you can access daily dumps of the previous day's Messages, Calls, Conferences, or conference Participants, eliminating the need to iterate through the list resource one page at a time to download your records. The BulkExport files are automatically removed after seven days. You can also use BulkExport to generate a set of historical daily dumps over a range of dates.

When a BulkExport completes, it can fire a webhook and/or send an email. This applies to the daily export if configured and to custom jobs. In both cases, successful exports will generate a Day resource for each day requested.

BulkExport is useful if you have:

  • A data warehouse where you want to store messaging traffic to perform analysis.
  • A compliance store where messaging should be retained so that you have a permanent record.
  • Requirements to produce data.

Base URL

base-url page anchor

Control over BulkExports and the data exported is available under the following URL:

https://bulkexports.twilio.com/v1/Exports/<resource_type>

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

exportconfiguration page anchor

The ExportConfiguration resource lets you specify if you have a Twilio Editions product, and 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.

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 subaccounts can request data for up to a total of 366 days within a UTC calendar day. If requesting a subaccount, the parent account will be used to determine the number of days being requested within a UTC calendar day. For instance, if you submit requests across several subaccounts, and the aggregate number of requested days exceeds 366 within 24 hours, 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 is completed. When a custom job completes, it will generate one Day resource for each day in the requested 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(link takes you to an external page) from the notification center on the console.

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

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.


ResourceDescription
ExportConfigurationConfigure export webhooks. Twilio Enterprise Edition(link takes you to an external page) customers can also set daily exports.
ExportCustomJobCreate new jobs to export data, and list current jobs and their status. Running a job will create the corresponding Days.
JobsView the status of current jobs, and delete incomplete custom jobs.
DaysList and fetch the exported message data for given days.

There are two ways to use BulkExport:

  1. If you have the Twilio Enterprise Edition(link takes you to an external page), 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.

You can also delete Call records; see the delete BulkExport Call records section below to learn how.


All Day files are stored and returned as compressed GZIP JSON files with one record per line.

All records have timestamps in UTC in ISO 8601 format.

Records differ slightly from their associated API resources. This section outlines the differences for Messages, Calls, Conferences, and Participants resources.

BulkExport Message records are similar to the Message resource. The differences are:

  • Price data may not be present for every Message record.
  • The following fields are not present:
    • price_units
    • api_version
    • error_message (but error_code is)
    • uri
    • subresource_uris (containing the media URLs)

BulkExport Call records are similar to the Calls resource. The differences are:

  • Price data may not be present for every Call record.
  • The following fields are not present:
    • uri
    • subresource_uris

You can delete BulkExport Call records. See the Delete archived Calls section below for more information.

BulkExport Conference records are similar to the Conferences resource. The differences are:

  • The following fields are not present:
    • api_version
    • uri
    • subresource_uris

BulkExport Participant records are similar to the Participants resource. The differences are:

  • The following fields are not present:
    • uri
    • label

Delete BulkExport Call records

delete-bulkexport-call-records page anchor

You can delete BulkExport Call records using the DELETE request shown below.

The BulkExport Call record is separate from the Call resource. Therefore:

  • This DELETE request does not delete the associated Call resource for Calls that are less than 13 months old. (However, If you delete a Call Resource, the Call's BulkExport record is also deleted.)
  • Calls older than 13 months are only accessible via BulkExport, and this DELETE request deletes the Call record.

Twilio handles BulkExport Call record deletions asynchronously and in batches. It may take up to one week for a BulkExport Call record to be removed.

Property nameTypeRequiredPIIDescription
Datestring<date>required
Not PII

The date of the Call in UTC.


SidSID<CA>required

The Twilio-provided Call SID that uniquely identifies the Call resource to delete

Pattern: ^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34
Delete an archived CallLink to code sample: Delete an archived Call
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function deleteArchivedCall() {
11
await client.voice.v1
12
.archivedCalls("2022-02-27", "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
.remove();
14
}
15
16
deleteArchivedCall();

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.