Create an export of data for a segment of users

Schedules an export based on the provided segment. The progress and results of the export can be fetched from the operations API.

Method: POST

URI: /segments/v1/exports

Parameters

NameTypeDescription
segmentIdstringRequired. An Id for a segment as returned from the list segments API endpoint. This can include built-in segment Ids such as the "everyone" segment.
typestringRequired. Which kind of data to export. TYPE_EVENT will export the event data for the corresponding segment and TYPE_INDIVIDUAL will export individuals in the segment.
formatstringRequired. Determines the data format of the export. Options are FORMAT_JSON, FORMAT_CSV, and FORMAT_NDJSON.
timeRangeTimeRangeRequired. Restricts the exported data to the provided time range. For TYPE_EVENT exports, this is based on the EventStart time. For TYPE_INDIVIDUAL, only users that performed events within the provided time range are exported.

Note: this does not have any effect on the underlying segment's time range.
segmentTimeRangeTimeRangeOptional. Overrides the time range for the provided segment.
timezonestringOptional. IANA time zone that should be used to calculate relative dates. Defaults to UTC
fieldsarray of stringsOptional. Restricts the set of fields that are included in the export. If unspecified, all fields will be exported.

Custom variables (such as user variables and custom event variables) can also be specified. These should be specified like user_MyUserVar_str or evt_MyEventVar_int. You can also get all of these by specifying them as like: user_* or evt_*. (Note: this is not a general glob pattern, just a special value)
eventDetailsEventDetailsOptional. Only applies to exports with type TYPE_EVENT.

TimeRange object parameters

NameTypeDescription
startstringUTC RFC 3339 timestamp or an empty string. If an empty string, this will be interpreted as "forever in the past".
endstringUTC RFC 3339 timestamp or an empty string. If an empty string, this will be interpreted as "up to the time of the request".

EventDetails object parameters

NameTypeDescription
scopestringSpecifies "scope" of the events to be exported relative to the events matching the segment’s event filters.

Options are SCOPE_EVENTS, SCOPE_INDIVIDUALS, SCOPE_SESSIONS, and SCOPE_PAGES. Defaults to SCOPE_EVENTS.

Request Headers

Authorization: Basic {YOUR_API_KEY}

Status Codes

200: A successful response.

Response Fields

NameTypeDescription
operationIdstringThis id can be used with the operations API to track the status of the export.

Export Types

Two types of segment-related data are available: individuals and events.

Individual Exports

An individual export will contain information about each of the individuals that match the provided segment. The fields that are available through this export are documented here.

Event Exports

An event export will contain events performed by individuals that match the provided segment. The fields that are available through this export are documented here.

Events are selected based on the scope parameter. In order of increasing scope:

  • SCOPE_EVENT: only events that match the segment's event criteria.
  • SCOPE_PAGES: all events from each page where users performed matching event criteria.
  • SCOPE_SESSIONS: all events from each session where users performed matching event criteria.
  • SCOPE_INDIVIDUAL: all events for each individual who performed matching event criteria.

Additional Information

Endpoint

POST https://api.fullstory.com/segments/v1/exports

Example Requests

Export all matching events for a segment

curl -X POST \
  https://api.fullstory.com/segments/v1/exports \
  -H 'content-type: application/json' \
  -H 'Authorization: Basic {YOUR_API_KEY}' \
  -d '{
    "segmentId": "alice@example.com:12345678910",
    "type": "TYPE_EVENT",
    "format": "FORMAT_JSON",
    "timeRange": {
      "start": "",
      "end": ""
    }
  }'

Export all events for sessions that match the segment search

curl -X POST \
  https://api.fullstory.com/segments/v1/exports \
  -H 'content-type: application/json' \
  -H 'Authorization: Basic {YOUR_API_KEY}' \
  -d '{
    "segmentId": "alice@example.com:12345678910",
    "type": "TYPE_EVENT",
    "eventDetails": {
      "scope": "SCOPE_SESSIONS"
    },
    "format": "FORMAT_JSON",
    "timeRange": {
      "start": "",
      "end": ""
    }
  }'

Export all individuals with activity in the month of October

curl -X POST \
  https://api.fullstory.com/segments/v1/exports \
  -H 'content-type: application/json' \
  -H 'Authorization: Basic {YOUR_API_KEY}' \
  -d '{
    "segmentId": "everyone",
    "type": "TYPE_INDIVIDUAL",
    "format": "FORMAT_CSV",
    "timeRange": {
      "start": "2020-10-01T00:00:00Z",
      "end": "2020-11-01T00:00:00Z"
    },
    "segmentTimeRange": {
      "start": "2020-10-01T00:00:00Z",
      "end": "2020-11-01T00:00:00Z"
    }
  }'

Example Response

{
  "operationId": "U0VBUkmIX1VYUE9SVFplcmRteUlPV3YyV3RnRVZCdxdSeVhScnZVcDhVYUdaY3BibEp4RGIxOVZV"
}