Skip to main content
GET
https://app.cometly.com
/
public-api
/
v1
/
events
List Events
curl --request GET \
  --url https://app.cometly.com/public-api/v1/events \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {}
  ],
  "path": "<string>",
  "per_page": 123,
  "next_cursor": {},
  "next_page_url": {},
  "prev_cursor": {},
  "prev_page_url": {},
  "message": "<string>"
}

​
Overview

This endpoint allows you to retrieve a list of events from Cometly with powerful filtering capabilities including date ranges, attribution models, sources, and field selection. Results are cursor-paginated for efficient data retrieval.

​
Query Parameters

​
Required Parameters

​
start_date
string
required
Start date for the query range in YYYY-MM-DD HH:MM:SS format. The timestamp is interpreted in your space’s timezone. Example: 2024-01-01 00:00:00
​
end_date
string
required
End date for the query range in YYYY-MM-DD HH:MM:SS format. Must be after start_date and is interpreted in your space’s timezone. Example: 2024-01-31 23:59:59

​
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 response.Limits: Minimum 1, maximum 20 fields. Duplicate values are not allowed.Note: id and event_time_utc are always included in the response. When sources are provided for attribution, touchpoint_id is also always included. These fields are required for cursor pagination to work properly.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)
  • order_id - Order identifier
  • order_name - Order name
Auto-included fields (not user-requestable):
  • id - Event identifier (always included for cursor pagination)
  • event_time_utc - Event timestamp in UTC (always included for cursor pagination)
  • touchpoint_id - Touchpoint identifier (automatically included when sources are provided for cursor pagination)
​
per_page
integer
default:"200"
Number of events to return per page. Minimum: 1, Maximum: 4000
​
cursor
string
Pagination cursor from a previous response. Use this to fetch the next page of results.

​
Response

​
Success Response

The response follows Laravel’s cursor pagination structure:
​
data
array
Array of event objects with the requested fields
​
path
string
The base URL path for the endpoint
​
per_page
integer
Number of items per page
​
next_cursor
string | null
Cursor for the next page of results. null if there are no more pages.
​
next_page_url
string | null
Full URL for the next page of results. null if there are no more pages.
​
prev_cursor
string | null
Cursor for the previous page of results. null if on the first page.
​
prev_page_url
string | null
Full URL for the previous page of results. null if on the first page.

​
Error Response

​
message
string
Error description explaining what went wrong

​
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"

# 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

Status CodeDescription
200Events successfully retrieved
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

​
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_id field requires sources to be provided, as it returns the platform-specific ad identifier from the attributed touchpoint
  • 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.