> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xtremepush.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Trigger Segment Export
> Used to trigger a background task to export device or profile data for a specific segment.
Prerequisites: Ensure you have the following:
- An active Xtremepush project
- Export and File Download scopes enabled for your API Client ID
- A valid OAuth 2.0 access token
- The segment_id or segment_title of the segment you want to export
## Segment Export Workflow
This API allows you to queue an asynchronous task to export segment data. The segment export process follows these three steps:
1. Call the /segment-export/trigger endpoint to start the export. The response contains a unique task_id.
2. Use the /info/task endpoint with the task_id to monitor the export progress. After the export is complete, a file_id is generated.
3. Call the /file/{fileId}/download endpoint using each file_id from the task result to retrieve your segment data.
## Export Capabilities and Restrictions
Before you queue an export, review the following:
- You can only trigger one export per hour for any specific segment.
- You must provide either a segment_id or a segment_title. You cannot provide both in the same request.
- There are two types of export options:
- device - exports device-level records.
- profile - exports user profile records. This type allows you to select specific attributes and subscription preferences to include in the generated file.
## OpenAPI
````json POST /segment-export/trigger
{
"openapi": "3.1.0",
"info": {
"title": "external-api",
"version": "1"
},
"servers": [
{
"url": "https://api.eu.xtremepush.com/api/external"
}
],
"paths": {
"/segment-export/trigger": {
"post": {
"summary": "Trigger Segment Export",
"description": "Used to trigger a background task to export device or profile data for a specific segment.\n\n
\n\nPrerequisites: Ensure you have the following:
\n\n- An active Xtremepush project
\n- Export and File Download scopes enabled for your API Client ID
\n- A valid OAuth 2.0 access token
\n- The segment_id or segment_title of the segment you want to export
\n\n
\n\n## Segment Export Workflow\n\nThis API allows you to queue an asynchronous task to export segment data. The segment export process follows these three steps:
\n\n1. Call the /segment-export/trigger endpoint to start the export. The response contains a unique task_id.
\n2. Use the /info/task endpoint with the task_id to monitor the export progress. After the export is complete, a file_id is generated.
\n3. Call the /file/{fileId}/download endpoint using each file_id from the task result to retrieve your segment data.
\n\n
\n\n## Export Capabilities and Restrictions\n\nBefore you queue an export, review the following:
\n\n- You can only trigger one export per hour for any specific segment.
\n- You must provide either a segment_id or a segment_title. You cannot provide both in the same request.
\n- There are two types of export options:
\n - device - exports device-level records.
\n - profile - exports user profile records. This type allows you to select specific attributes and subscription preferences to include in the generated file.
",
"operationId": "post_segment-export-trigger",
"parameters": [
{
"in": "header",
"name": "Authorization",
"schema": {
"type": "string"
},
"required": "true",
"description": "The OAuth 2.0 bearer token. Example: Bearer {your_token}"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"export_type"
],
"properties": {
"segment_id": {
"type": "integer",
"description": "The unique identifier of the segment you want to export. You must provide this if you do not provide a segment_title."
},
"segment_title": {
"type": "string",
"description": "The exact name of the segment you want to export. You must provide this if you do not provide a segment_id."
},
"export_type": {
"type": "string",
"description": "Defines the type of data to export. Use \"device\" for device-level records or \"profile\" for profile-level records."
},
"attributes": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of profile attributes to include in profile exports, for example [\"user_id\", \"email\", \"first_name\"]. This field must be null or an empty array for device exports."
},
"preferences": {
"type": "array",
"items": {
"type": "integer"
},
"description": "A list of subscription preferences to include in profile exports. This field must be null or an empty array for device exports."
}
}
},
"examples": {
"Profile export": {
"value": {
"segment_id": "12345",
"export_type": "profile",
"attributes": [
"user_id",
"email",
"first_name"
],
"preferences": []
}
},
"Device export": {
"value": {
"segment_id": "12345",
"export_type": "device",
"attributes": [],
"preferences": []
}
}
}
}
}
},
"responses": {
"202": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"default": "true",
"description": "Returns true when the request is successful."
},
"message": {
"type": "string",
"default": "Segment export queued successfully"
},
"data": {
"type": "object",
"properties": {
"task_id": {
"type": "integer",
"description": "The unique identifier for the export task. Use this ID to check the status of your export."
}
}
}
}
},
"examples": {
"Result": {
"value": {
"success": "true",
"message": "Segment export queued successfully"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"default": "Bad Request"
},
"message": {
"type": "string",
"default": "Project is inactive or Validation failed"
}
}
},
"examples": {
"Result": {
"value": {
"name": "Bad Request",
"message": "Project is inactive or Validation failed"
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"default": "Forbidden"
},
"message": {
"type": "string",
"default": "Access Denied"
}
}
},
"examples": {
"Result": {
"value": {
"name": "Forbidden",
"message": "Access Denied"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"default": "Not Found"
},
"message": {
"type": "string",
"default": "Segment not found"
}
}
},
"examples": {
"Result": {
"value": {
"name": "Not Found",
"message": "Segment not found"
}
}
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"default": "Too Many Requests"
},
"message": {
"type": "string",
"default": "Rate Limit Exceeded"
}
}
},
"examples": {
"Result": {
"value": {
"name": "Too Many Requests",
"message": "Rate Limit Exceeded"
}
}
}
}
}
}
},
"tags": [
"Segment Export Methods"
]
}
}
}
}
````