Skip to main content
POST
https://app.cometly.com
/
public-api
/
v1
/
events
/
exports
Create Event Export
curl --request POST \
  --url https://app.cometly.com/public-api/v1/events/exports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "date": "<string>",
  "query_mode": "<string>",
  "event_names": [
    "<string>"
  ],
  "sources": [
    "<string>"
  ],
  "attribution_model": "<string>",
  "attribution_window": 123,
  "fields": [
    "<string>"
  ]
}
'
{
  "export_id": 123,
  "status": "<string>",
  "message": "<string>"
}

​
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 endpoint instead.
When to use exports: See Exports vs Pagination 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.
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_adsOrganic: 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_organicAI Platforms: ai_chat_gpt, ai_perplexity, ai_copilot, ai_claude, ai_grok, ai_gemini, ai_deepseekOther: 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.Available fields:
  • profile_id - Contact profile identifier
  • company_id - Company identifier
  • space_id - Space identifier
  • event_name - Event name
  • amount - Transaction amount
  • is_upsell - Upsell flag
  • ad_id - Platform-specific ad identifier (requires sources to be provided)
  • order_id - Order identifier
  • order_name - Order name

​
Response

​
Success Response (202 Accepted)

​
export_id
integer
Unique identifier for the export job. Use this to check status with the Get Event Export 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. 
{"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

# 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"]
  }'

​
Status Codes

Status CodeDescription
202Export job created and queued for processing
401Missing or invalid API key
403API key doesn’t have permission or subscription is inactive
422Invalid parameters provided (check error message for details)
429Too many requests - rate limit exceeded. See Rate Limiting

​
Next Steps

After creating an export, you need to poll the 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 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 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
  • 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