Request profile in segment event export

Profile in segment event export

Request profile in segment event export. The export can be requested for specific segment or based on event dates and the data can include attributes, tags, events and topic state.

When segment_filter request parameter is provided, only the profiles from the selected segment are exported, otherwise the export file contains all profiles on the account.

Only the attributes, tags and events explicitly declared in the corresponding request parameters are exported. Even though you're only interested in events, you still need to request at least one attribute or tag for the profiles to even show up in the export file.

Time window for events

For events use start_at (mandatory) and end_at parameters to specify the time period for the exported events. When end_at is not provided in a request, it is defaulted to one week after start_at.

Restrain the event time window as much as you can for your use case. Shorter time windows result in faster export processing and smaller export files that are also quicker to transfer and process. This is especially relevant for larger data sets (high number of very active profiles) and when segment_filter with complex queries is used.

How to use

Once executed successfully, this endpoint returns a poll URL that is valid for 1 day.

Call this URL repeatedly with exponential back-off using the same authentication token as for the other APSIS One API calls. Until the result is ready, you will keep getting HTTP 404 Not Found response status code.

As soon as the export file is ready, the poll URL returns HTTP 200 OK and starts streaming a export file as a response.

The HTTP 410 Gone means that the file is no longer available or the ID used is invalid.

In rare cases when the export processing has failed, calling the poll URL returns HTTP 503 Service Unavailable. If that happens, please request a new export with the POST endpoint.

Compression

By default the export file is an uncompressed JSON so your code should treat it as .json. If you prefer a compressed export, provide Accept-Encoding: gzip request header when calling the poll URL. The response will then contain Content-Encoding: gzip header and you will be able to handle the file as .json.gz.

You can download the same export multiple times using the same poll URL with or without compression.

Export file

The export file is in the JSON format.

On the top level there is a JSON dictionary with profiles. The keys in this dictionary are profile export keys.

For each profile, export file contains sections JSON dictionary. The keys in this dictionary are section IDs. Use "Get sections" endpoint of this API to map these IDs to the specific section definitions.

Each section contains both, attributes and tags, inside the attributes JSON dictionary. The keys in this dictionary are IDs of the attributes and tags. Use "Get attributes" and "Get tags" endpoints of this API to map these IDs to the specific attribute and tag definitions. The objects in this dictionary have the following properties:

• value

  The data type of this property depends on the attribute type. For tags the value is always null and the sheer fact that the attribute exists in the export file means that the corresponding profile was tagged with this particular tag.

If any event type has been requested for a specified section, the corresponding section object also contains events JSON array. Each object in this array represents a single event and contains the following information:

• correlationId

  ID for the event assigned by the event source (Email Tool). The same correlationId value may be repeated if the event has been sent multiple times due to a retry logic.

• sourceEventTime

  Time of the event in milliseconds since Unix epoch reported by the event source. This feature was introduced at the beginning of 2020 so events prior to that may have event_time equal to 0. The value of 0 is also possible when the event source did not specify the event time.

• typeId

  Event version ID. Use "Get events" endpoint of the API to map these IDs to the specific event definitions.

• createdAt

  Time of the event in milliseconds since Unix epoch as seen on Audience server when it received the event.

• data

  Data specific to a particular event type as defined by "Get events" endpoint of the API

Limits

The export file can include up to 75 attributes and 25 tags. Validated when requesting an export.

Pending export count limit. If reached, HTTP 429 Too Many Requests is returned.

If you request an export with many attributes or a large time window that results in many events, you may receive a status of error when attempting to request or download an export. You can then retry the export request aiming at a smaller data subset.

Usually the errors in processing are caused by:

• using too complex segments
• providing too many attributes and/or tags
• providing too many event types

More information

Video guides

Accept-Encoding request header