> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cometly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Event Export

> Create an asynchronous export job to generate a downloadable file of events

## Overview

This endpoint creates an asynchronous export job that generates a downloadable file containing events data. The export is processed in the background and returns a presigned download URL when complete.

Use this endpoint when you need to extract large volumes of event data (10,000+ events) efficiently. For real-time needs, use the [List Events](https://docs.cometly.com/api-reference/endpoint/list-events.md) endpoint instead.

> [!NOTE]
>
> **When to use exports**: See [Exports vs Pagination](https://docs.cometly.com/concepts/exports-vs-pagination.md) to understand when to use exports versus the paginated list endpoint.

## Request Body

### Required Parameters

**date** `string` *required*

The date to export events for in `YYYY-MM-DD` format. The date is interpreted in your space's timezone and exports events from 00:00:00 to 23:59:59 for that day.

**Limit**: Maximum 1 day per export.

Example: `2024-01-15`

### Optional Parameters

**query\_mode** `string` (default: profile)

Determines whether to report metrics by contact or company level.

Options:

* `profile` - Contact-level events (default)
* `company` - Company-level events

**event\_names** `string[]`

Filter results to specific event names. Defaults to all events when omitted.

**Limits:** Minimum 1, maximum 10 event names. Duplicate values are not allowed.

Values:

* `add_payment_info`
* `add_to_cart`
* `complete_registration`
* `contact`
* `initiate_checkout`
* `lead_generated`
* `purchase`
* `schedule`
* `sign_up`
* `start_trial`
* `submit_application`
* `subscribe`
* `upsell_purchase`
* `view_content`
* `webinar_registration`

Custom events: `custom_event_1` through `custom_event_50`.

**sources** `string[]`

Filter events by traffic sources. When provided, `attribution_model` and `attribution_window` become required.

**Limits:** Minimum 1, maximum 15 sources. Duplicate values are not allowed.

> [accordion] Available sources
>
> **Paid Ads:**
> `facebook_ads`, `google_ads`, `linkedin_ads`, `tiktok_ads`, `youtube_ads`, `instagram_ads`, `bing_ads`, `yahoo_ads`, `pinterest_ads`, `reddit_ads`, `snapchat_ads`, `telegram_ads`, `twitch_ads`, `x_ads`, `quora_ads`, `duckduckgo_ads`, `whop_ads`, `chatgpt_ads`
>
> **Organic:**
> `facebook_organic`, `google_organic`, `linkedin_organic`, `tiktok_organic`, `youtube_organic`, `instagram_organic`, `bing_organic`, `yahoo_organic`, `pinterest_organic`, `reddit_organic`, `snapchat_organic`, `telegram_organic`, `twitch_organic`, `x_organic`, `quora_organic`, `duckduckgo_organic`, `messenger_organic`, `brave_organic`, `threads_organic`
>
> **AI Platforms:**
> `ai_chat_gpt`, `ai_perplexity`, `ai_copilot`, `ai_claude`, `ai_grok`, `ai_gemini`, `ai_deepseek`
>
> **Other:**
> `email`, `sms`, `referral`, `direct`, `shop_app`, `substack`, `capterra`, `trustpilot`, `g2`, `yelp`

**attribution\_model** `string`

Attribution model to use for filtering events. Required when `sources` is provided.

Options:

* `first_touch` - First interaction attribution
* `last_touch` - Last interaction attribution
* `linear` - Equal credit across all touchpoints
* `first_platform_touch` - First paid platform touch
* `last_platform_touch` - Last paid platform touch
* `linear_paid` - Linear attribution across paid touchpoints only
* `u_shaped` - 40% first, 40% last, 20% middle touchpoints
* `last_non_direct_touch` - Last touch excluding direct traffic

**attribution\_window** `integer`

Attribution lookback window in days. Required when `sources` is provided.

Options: `0` (LTV), `1`, `7`, `14`, `30`, `60`, `90`

**fields** `string[]` (default: \['id', 'event\_time\_utc'])

Specify which fields to include in the exported file.

**Limits:** Minimum 1, maximum 20 fields. Duplicate values are not allowed.

**Note:** `id` and `event_time_utc` are always included in the export. When `sources` are provided for attribution, `touchpoint_id` is also always included.

Available fields:

* `profile_id` - Contact profile identifier
* `company_id` - Company identifier
* `space_id` - Space identifier
* `event_name` - Event name
* `configured_name` - The configured name of the event. For custom events (`custom_event_1` through `custom_event_50`), this is the user-configured name. For standard events, this equals `event_name`.
* `amount` - Transaction amount (with attribution, this is the partial amount credited to the touchpoint)
* `is_upsell` - Upsell flag
* `ad_id` - Platform-specific ad identifier (requires `sources` to be provided)
* `ad_name` - Ad name from the ad platform (requires `sources` to be provided)
* `adset_id` - Platform-specific ad set identifier (requires `sources` to be provided)
* `adset_name` - Ad set name from the ad platform (requires `sources` to be provided)
* `campaign_id` - Platform-specific campaign identifier (requires `sources` to be provided)
* `campaign_name` - Campaign name from the ad platform (requires `sources` to be provided)
* `account_id` - Platform-specific ad account identifier (requires `sources` to be provided)
* `account_name` - Ad account name from the ad platform (requires `sources` to be provided)
* `order_id` - Order identifier
* `order_name` - Order name
* `event_url` - The full URL where the event occurred

**Auto-included fields (not user-requestable):**

* `id` - Event identifier (always included)
* `event_time_utc` - Event timestamp in UTC (always included)
* `touchpoint_id` - Touchpoint identifier (automatically included when sources are provided)
* `source` - Traffic source (automatically included when any ad hierarchy field is requested: `ad_id`, `ad_name`, `adset_id`, `adset_name`, `campaign_id`, `campaign_name`, `account_id`, `account_name`)

## Response

### Success Response (202 Accepted)

**export\_id** `string`

Unique identifier for the export job. Use this to check status with the [Get Event Export](https://docs.cometly.com/api-reference/endpoint/get-event-export.md) endpoint.

**status** `string`

Current status of the export. Will be `queued` immediately after creation.

### Error Response

**message** `string`

Error description explaining what went wrong

## Export File Format

Completed exports are delivered as **gzipped NDJSON** (Newline-Delimited JSON) files. Each line contains a complete JSON object representing one event record.

```json theme={null}
{"id":"123","event_name":"purchase","amount":99.99,"event_time_utc":"2024-01-15T10:23:45Z"}
{"id":"124","event_name":"sign_up","amount":0,"event_time_utc":"2024-01-15T10:24:12Z"}
{"id":"125","event_name":"purchase","amount":149.50,"event_time_utc":"2024-01-15T10:25:33Z"}
```

This format is ideal for streaming and processing large files line-by-line without loading the entire file into memory.

## Example Requests

```bash cURL theme={null}
# Create export for a single day with minimal parameters
curl -X POST "https://app.cometly.com/public-api/v1/events/exports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2024-01-15"
  }'

# Create export with event filtering and specific fields
curl -X POST "https://app.cometly.com/public-api/v1/events/exports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2024-01-15",
    "query_mode": "profile",
    "event_names": ["purchase", "sign_up"],
    "fields": ["id", "event_name", "amount", "profile_id", "event_time_utc"]
  }'

# Create export with attribution filtering
curl -X POST "https://app.cometly.com/public-api/v1/events/exports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2024-01-15",
    "sources": ["facebook_ads", "google_ads"],
    "attribution_model": "last_touch",
    "attribution_window": 30,
    "fields": ["id", "event_name", "amount", "ad_id", "event_time_utc"]
  }'
```

```javascript JavaScript theme={null}
// Create export for a single day with minimal parameters
const response = await fetch('https://app.cometly.com/public-api/v1/events/exports', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    date: '2024-01-15'
  })
});

const data = await response.json();
console.log(`Export created: ${data.export_id}, Status: ${data.status}`);

// Create export with event filtering and specific fields
const filteredResponse = await fetch('https://app.cometly.com/public-api/v1/events/exports', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    date: '2024-01-15',
    query_mode: 'profile',
    event_names: ['purchase', 'sign_up'],
    fields: ['id', 'event_name', 'amount', 'profile_id', 'event_time_utc']
  })
});

const filteredData = await filteredResponse.json();

// Create export with attribution filtering
const attributedResponse = await fetch('https://app.cometly.com/public-api/v1/events/exports', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    date: '2024-01-15',
    sources: ['facebook_ads', 'google_ads'],
    attribution_model: 'last_touch',
    attribution_window: 30,
    fields: ['id', 'event_name', 'amount', 'ad_id', 'event_time_utc']
  })
});

const attributedData = await attributedResponse.json();
```

```php PHP theme={null}
<?php
// Create export for a single day with minimal parameters
$baseUrl = 'https://app.cometly.com/public-api/v1/events/exports';
$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Accept: application/json',
    'Content-Type: application/json'
];

$data = json_encode([
    'date' => '2024-01-15'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);

echo "Export created: {$result['export_id']}, Status: {$result['status']}\n";

// Create export with event filtering and specific fields
$filteredData = json_encode([
    'date' => '2024-01-15',
    'query_mode' => 'profile',
    'event_names' => ['purchase', 'sign_up'],
    'fields' => ['id', 'event_name', 'amount', 'profile_id', 'event_time_utc']
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $filteredData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$filteredResponse = curl_exec($ch);
$filteredResult = json_decode($filteredResponse, true);
curl_close($ch);

// Create export with attribution filtering
$attributedData = json_encode([
    'date' => '2024-01-15',
    'sources' => ['facebook_ads', 'google_ads'],
    'attribution_model' => 'last_touch',
    'attribution_window' => 30,
    'fields' => ['id', 'event_name', 'amount', 'ad_id', 'event_time_utc']
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $attributedData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$attributedResponse = curl_exec($ch);
$attributedResult = json_decode($attributedResponse, true);
curl_close($ch);
?>
```

```python Python theme={null}
import requests
import json

# Create export for a single day with minimal parameters
base_url = 'https://app.cometly.com/public-api/v1/events/exports'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
}

data = {
    'date': '2024-01-15'
}

response = requests.post(base_url, headers=headers, json=data)
result = response.json()
print(f"Export created: {result['export_id']}, Status: {result['status']}")

# Create export with event filtering and specific fields
filtered_data = {
    'date': '2024-01-15',
    'query_mode': 'profile',
    'event_names': ['purchase', 'sign_up'],
    'fields': ['id', 'event_name', 'amount', 'profile_id', 'event_time_utc']
}

filtered_response = requests.post(base_url, headers=headers, json=filtered_data)
filtered_result = filtered_response.json()

# Create export with attribution filtering
attributed_data = {
    'date': '2024-01-15',
    'sources': ['facebook_ads', 'google_ads'],
    'attribution_model': 'last_touch',
    'attribution_window': 30,
    'fields': ['id', 'event_name', 'amount', 'ad_id', 'event_time_utc']
}

attributed_response = requests.post(base_url, headers=headers, json=attributed_data)
attributed_result = attributed_response.json()
```

## Status Codes

| Status Code | Description |
| - | - |
| 202 | Export job created and queued for processing |
| 401 | Missing or invalid API key |
| 403 | API key doesn't have permission or subscription is inactive |
| 422 | Invalid parameters provided (check error message for details) |
| 429 | Too many requests - rate limit exceeded. See [Rate Limiting](https://docs.cometly.com/introduction/rate-limiting.md) |

## Next Steps

After creating an export, you need to poll the [Get Event Export](https://docs.cometly.com/api-reference/endpoint/get-event-export.md) endpoint to check the status and retrieve the download URL when ready.

## Notes

* **Rate Limit**: This endpoint has a limit of **5 requests per minute** per Space. See [Rate Limiting](https://docs.cometly.com/introduction/rate-limiting.md) for details.
* **Processing Time**: Exports typically complete within seconds to a few minutes depending on data volume
* **Max Date Range**: Each export can only contain **one day** of data (00:00:00 to 23:59:59 in your space's timezone)
* **Export Capacity**: Can handle 100,000+ events per day efficiently
* **Status Checking**: Use the [Get Event Export](https://docs.cometly.com/api-reference/endpoint/get-event-export.md) endpoint to check status (30 requests/min limit)
* **Attribution Breakdown**: With multi-touch attribution models (linear, u\_shaped, linear\_paid), each event may generate multiple rows in the export - one per attributed touchpoint. Each row contains the touchpoint's partial credit (e.g., a \$100 conversion with 4 touchpoints returns 4 rows with \$25 each). Single-touch models (first\_touch, last\_touch) return one row per event.
* When `sources` are not provided, all events in the specified date are exported without attribution filtering
* The ad hierarchy fields (`ad_id`, `ad_name`, `adset_id`, `adset_name`, `campaign_id`, `campaign_name`, `account_id`, `account_name`) require `sources` to be provided. Requesting higher-level hierarchy fields (such as `account_name`) may increase processing time compared to requesting only lower-level fields (such as `ad_name`), so selecting only the fields you need will generally be more efficient.
* By default, only `id` and `event_time_utc` are included in the export (plus `touchpoint_id` when using attribution). Specify additional fields as needed to minimize file size.
* **File Expiration**: Download URLs expire after 15 minutes for security. Retrieve the file promptly after completion.
* **Security**: Export files use UUID-based filenames with time-limited presigned URLs to prevent unauthorized access


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.