List Events

​

Overview

​

Query Parameters

​

Required Parameters

​

Optional Parameters

​

Response

​

Success Response

​

Error Response

​

Example Requests

# Basic request with only required parameters
curl -G "https://app.cometly.com/public-api/v1/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "start_date=2024-01-01 00:00:00" \
  -d "end_date=2024-01-31 23:59:59"

# Request with attribution filtering and specific fields
curl -G "https://app.cometly.com/public-api/v1/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "start_date=2024-01-01 00:00:00" \
  -d "end_date=2024-01-31 23:59:59" \
  -d "query_mode=profile" \
  -d "event_names[]=purchase" \
  -d "event_names[]=sign_up" \
  -d "sources[]=facebook_ads" \
  -d "sources[]=google_ads" \
  -d "attribution_model=last_touch" \
  -d "attribution_window=30" \
  -d "fields[]=id" \
  -d "fields[]=event_name" \
  -d "fields[]=amount" \
  -d "fields[]=event_time_utc" \
  -d "per_page=100"

# Filter events by the owning contact's custom field value
curl -G "https://app.cometly.com/public-api/v1/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "start_date=2024-01-01 00:00:00" \
  -d "end_date=2024-01-31 23:59:59" \
  -d "event_names[]=purchase" \
  -d "custom_field_filters[0][field]=profile_field_5" \
  -d "custom_field_filters[0][operator]=equal_to" \
  -d "custom_field_filters[0][value]=Premium"

# Pagination request using cursor
curl -G "https://app.cometly.com/public-api/v1/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "start_date=2024-01-01 00:00:00" \
  -d "end_date=2024-01-31 23:59:59" \
  -d "cursor=eyJldmVudF90aW1lX3V0YyI6IjIwMjQtMDEtMTUgMTI..."

​

Status Codes

​

Notes

• Rate Limit: This endpoint has a limit of 7 requests per minute per Space. See Rate Limiting for details.
• When sources are provided, attribution filtering is applied and only events matching the attribution criteria are returned
• Attribution Breakdown: With multi-touch attribution models (linear, u_shaped, linear_paid), each event may return multiple rows - 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 range are returned without attribution filtering (one row per event)
• 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.
• Cursor pagination is used for efficient traversal of large result sets
• The id and event_time_utc fields are always included in responses. When attribution is used (sources provided), touchpoint_id is also always included.
• Dates are provided in your space’s configured timezone
• By default, only id and event_time_utc are returned (plus touchpoint_id when using attribution). Specify additional fields as needed to minimize response size.
• Custom Field Filters: Use custom_field_filters to narrow results to events whose owning contact matches conditions on custom profile fields. Filters are AND-joined; up to 10 per request. Slots that haven’t been configured with a label in your space are rejected with a 422. Age operators (age_greater_than, age_equal_to, age_less_than) accept a whole-number day count and are supported on date fields. The _ and \ characters in text filter values are treated as literals, not LIKE wildcards.