Bulk Activity Extract

Bulk Activity Extract Endpoint Reference

The Bulk Activity Extract set of REST APIs provides a programmatic interface for retrieving large amounts of activity data out of Marketo.  For cases which do not require low latency, and need to transfer significant volumes of activity data out of Marketo, such as CRM-integration, ETL, data warehousing, and data archiving.

Permissions


The Bulk Activity Extract APIs requires that the owning API user have the Read-Only Activity permission.

Filters

Filter Type Data Type Required Notes
 createdAt Date Range  Yes  Accepts a JSON object with the members “startAt” and “endAt”.  startAt accepts a datetime representing the low-watermark, and endAt accepts a datetime representing the high-watermark.  The range must be 30 days or fewer.  Jobs with this filter type will return all accessible records which were created within the date range.  Datetimes should be in an ISO-8601 format, without miliseconds.
 activityTypeIds Array[Integer] No Accepts a JSON object with one member, “activityTypeIds”.  The value should be an array of integers, corresponding to the desired activity types.  The Ids of activity types can be retrieved with the Get Activity Types endpoint.

Options

Parameter Data Type Required Notes
filter Array[Object] Yes Accepts an array of filters.  Exactly one createdAt filter must be included in the array.  An optional activityTypeIds filter may be included.

The filters are applied to the accessible activity set, and the resulting set of activities is returned by the export job.

format String No  Accepts one of: CSV, TSV, SSV  The exported file will be rendered as a comma-separated values, tab-separated values, or semi-colon separated values file, respectively if set.  Defaults to CSV if unset.
 columnHeaderNames Object No A JSON object containing key-value pairs of field and column header names. The key must be the name of a field included in the export job. The value will be the name of the exported column header for that field.
fields String No Optional comma-separated list to indicate the fields to be returned.  Default fields are: marketoGUID, leadId, activityDate, activityTypeId, campaignId, primaryAttributeValueId, primaryAttributeValue, attributes.  Fields may only be filtered out when exporting activities.

Creating a Job

To export records, you first need to define the job and the set of records that you want to retrieve.  When exporting activities there are two primary filters which can be applied: createdAt, which is always required, and activityTypeIds, which is optional.  The createdAt filter is used to define a date range in which activities were created, using the “startAt” and “endAt” parameters, both of which are datetime fields, and represent the earliest permitted creation date, and the latest permitted creation date respectively.  You may also optionally filter on only certain types of activities, using the activityTypeIds filter.  This is very useful for removing results which are not relevant for your use case.

The job now has a status of “Created,” but it is not yet in the processing queue.  To put it in the queue so it can begin processing, we need to call the enqueue.json endpoint using the exportId from the creation status response.

Now the status is reporting that the job has been queued.  When a worker becomes available for this job, then the status will be switched to “Processing” and the job will begin aggregating records from Marketo.

Polling Job Status

Marketo’s Bulk Activity Extract is an asynchronous endpoint, so the job status must be polled to determine when the job is complete.

The status endpoint may respond with any one of: Created, Queued, Processing, Canceled, Completed, Failed.

Retrieving Your Data

Once the job is complete, you can retrieve your data using the file.json endpoint.

The response will contain a file formatted in the way that the job was configured.  The endpoint will respond with the contents of the file.  To support partial and resumption-friendly retrieval of extracted data, the file endpoint optionally supports the HTTP header “Range” of the type “bytes”.  If the header is not set, the whole of the contents will be returned.  You can read more about using the Range header with Marketo Bulk Extract files here.

Cancelling a Job

If a job was configured incorrectly, or becomes unnecessary, it can be easily cancelled:

This will respond with a status indicating that the job has been cancelled.