> ## 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](/api-reference/endpoint/list-events) endpoint instead.

<Info>
  **When to use exports**: See [Exports vs Pagination](/concepts/exports-vs-pagination) to understand when to use exports versus the paginated list endpoint.
</Info>

## Request Body

### Required Parameters

<ParamField body="date" type="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`
</ParamField>

### Optional Parameters

<ParamField body="query_mode" type="string" default="profile">
  Determines whether to report metrics by contact or company level.

  Options:

  * `profile` - Contact-level events (default)
  * `company` - Company-level events
</ParamField>

<ParamField body="event_names" type="string[]" placeholder="['purchase', 'lead_generated']">
  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`.
</ParamField>

<ParamField body="sources" type="string[]" placeholder="['facebook_ads', 'google_ads']">
  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 title="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`

    **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`
  </Accordion>
</ParamField>

<ParamField body="attribution_model" type="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
</ParamField>

<ParamField body="attribution_window" type="integer">
  Attribution lookback window in days. Required when `sources` is provided.

  Options: `0` (LTV), `1`, `7`, `14`, `30`, `60`, `90`
</ParamField>

<ParamField body="fields" type="string[]" default="['id', 'event_time_utc']" placeholder="['id', 'event_name', 'amount']">
  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`)
</ParamField>

## Response

### Success Response (202 Accepted)

<ResponseField name="export_id" type="integer">
  Unique identifier for the export job. Use this to check status with the [Get Event Export](/api-reference/endpoint/get-event-export) endpoint.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the export. Will be `queued` immediately after creation.
</ResponseField>

### Error Response

<ResponseField name="message" type="string">
  Error description explaining what went wrong
</ResponseField>

## 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

<CodeGroup>
  ```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()
  ```
</CodeGroup>

## 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](/introduction/rate-limiting) |

## Next Steps

After creating an export, you need to poll the [Get Event Export](/api-reference/endpoint/get-event-export) 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](/introduction/rate-limiting) 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](/api-reference/endpoint/get-event-export) 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