Bulk Activity Extract

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.

Request

1

POST/bulk/v1/activities/export/create.json

Body

1

2

3

4

5

6

7

8

9

10

11

12

13

14

{

"format":"CSV",

"filter":{

"createdAt":{

"startAt":"",

"endAt":""

},

"activityTypeIds":[

1,

12,

13

]

}

}

Response

1

2

3

4

5

6

7

8

9

10

11

12

13

{

"requestId":"e42b#14272d07d78",

"success":true,

"result":[

{

"exportId":"ce45a7a1-f19d-4ce2-882c-a3c795940a7d",

"status":"Created",

"createdAt":"2017-01-21T11:47:30-08:00",

"queuedAt":"2017-01-21T11:48:30-08:00",

"format":"CSV"

}

]

}

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.

Request

1

POST/bulk/v1/activities/export/{exportId}/enqueue.json

Response

1

2

3

4

5

6

7

8

9

10

11

12

13

{

"requestId":"e42b#14272d07d78",

"success":true,

"result":[

{

"exportId":"ce45a7a1-f19d-4ce2-882c-a3c795940a7d",

"status":"Queued",

"createdAt":"2017-01-21T11:47:30-08:00",

"queuedAt":"2017-01-21T11:48:30-08:00",

"format":"CSV"

}

]

}

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.

Request

1

GET/bulk/v1/activities/export/{exportId}/status.json

Response

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

{

"requestId":"e42b#14272d07d78",

"success":true,

"result":[

{

"exportId":"ce45a7a1-f19d-4ce2-882c-a3c795940a7d",

"status":"Completed",

"createdAt":"2017-01-21T11:47:30-08:00",

"queuedAt":"2017-01-21T11:48:30-08:00",

"startedAt":"2017-01-21T11:51:30-08:00",

"finishedAt":"2017-01-21T12:59:30-08:00",

"format":"CSV",

"numberOfRecords":15423,

"fileSize":12342

}

]

}

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.

Request

1

GET/bulk/v1/activities/export/{exportId}/file.json

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:

Request

1

POST/bulk/v1/activities/export/{exportId}/cancel.json

Response

1

2

3

4

5

6

7

8

9

10

11

12

{

"requestId":"e42b#14272d07d78",

"success":true,

"result":[

{

"exportId":"ce45a7a1-f19d-4ce2-882c-a3c795940a7d",

"status":"Cancelled",

"createdAt":"2017-01-21T11:47:30-08:00",

"format":"CSV"

}

]

}

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

Latest Blog Posts

Keep up with what's new in the developer world

Important Change to Activity Records in Marketo APIs March 1, 2017 Note: This post will be updated to reflect changes made to activity records returned by the API due to migration to new infrastructure.
With the rollout of Marketo’s next-generation Activity Service beginning in Septmeber, we will be unable to enforce the uniqueness or presence of the integer “id” field in activities, data value changes, or lead deletion ... Read More >

Internet of Things for Marketers with IFTTT and Zapier June 20, 2017 The Internet of Things (IoT) is the inter-networking of connected devices, appliances, wearables, vehicles, etc. with embedded electronics, software, sensors, and network connectivity that enable these objects to collect and exchange data with cloud information systems. These technologies are growing and trending so fast that they will impact how we live, how we work and ... Read More >

Spring 2017 Updates June 16, 2017 In the Spring 2017 release, we are adding the ability to bulk extract lead and activity object data asynchronously, and to manipulate named account lists. See the full list of updates below.
Lead Database APIs
Bulk Extract of Leads
New endpoints to support extraction of leads in bulk. Specify record selection criteria using a variety of options. Details can ... Read More >