Skip to main content

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.

Returns one row per contact (profile) created in the date range, with primary email, name, phone, and location. Optionally enriched with all known emails, Cometly tracking tokens, or the full set of custom profile fields.

​
When to use

  • “Who signed up last week?”
  • “List leads from this month.”
  • “Show me new contacts created today.”
  • “Find contacts where Customer Plan is Premium.”
For a single contact’s full journey, use get_contact. For ad-performance questions, use query_ad_metrics.

​
Parameters

ParameterTypeRequiredDescription
start_datestringYesYYYY-MM-DD HH:MM:SS, interpreted in your Space’s timezone. Filters by contact creation date.
end_datestringYesYYYY-MM-DD HH:MM:SS, must be after start_date.
per_pageintegerNo1–5000. Default 200.
cursorstringNoPagination cursor from a prior response’s next_cursor.
include_all_emailsbooleanNoAdds an array of all known email addresses per contact (including merged profiles).
include_comet_tokensbooleanNoAdds the contact’s last 5 Cometly tracking tokens.
include_custom_fieldsbooleanNoIncludes the 30 custom profile fields (profile_field_1 through profile_field_30).
use_custom_field_labelsbooleanNoWhen include_custom_fields is true, replaces raw column names with user-defined labels (e.g. "Customer Age"). Always set this to true unless the user explicitly wants raw column names.
custom_field_filtersarrayNoAND-joined conditions on custom profile fields. See below.

​
Custom field filters

Flat array of AND-joined conditions referencing slots configured on your Space: 
[
  { "field": "profile_field_5",  "operator": "equal_to",     "value": "Premium" },
  { "field": "profile_field_18", "operator": "greater_than", "value": 30 },
  { "field": "profile_field_27", "operator": "between",      "start": "2025-01-01", "end": "2025-12-31" }
]
The tool’s input schema lists the labels and types your Space has configured for slots 1–30, so the model picks the right slug automatically when you mention a user-facing label like “Customer Plan” or “Customer Age.” Slots that haven’t been configured are rejected with validation_error. Maximum 10 conditions per request.

​
Operator vocabulary by field type

Slot rangeTypeOperators
profile_field_1 – profile_field_15textequal_to, not_equal_to, contains, not_contains, starts_with, ends_with, contains_word, any, unknown
profile_field_16 – profile_field_25numberequal_to, not_equal_to, greater_than, greater_than_or_equal_to, less_than, less_than_or_equal_to, any, unknown
profile_field_26 – profile_field_30dateequal_to, between, greater_than, less_than, age_greater_than, age_equal_to, age_less_than, any, unknown
any matches contacts where the field has a value; unknown matches contacts where the field is empty or unset. For numeric fields, any requires a value greater than 0 and unknown matches 0 or unset. Date comparisons (equal_to, greater_than, less_than, between) use your space’s configured timezone; equal_to matches the full calendar day.

​
Example response

{
  "data": [
    {
      "id": 41902,
      "email": "jane@example.com",
      "name": "Jane Doe",
      "phone": null,
      "location": "Austin, TX, US",
      "Customer Plan": "Premium",
      "Customer Age": 34
    }
  ],
  "next_cursor": "eyJpZCI6NDE5MDJ9",
  "prev_cursor": null,
  "per_page": 200
}
When use_custom_field_labels is true, the response keys carry the labels you configured ("Customer Plan", "Customer Age"); otherwise they appear as raw profile_field_N keys.

​
Caveats

  • Primary data only. The list endpoint returns one email, name, phone, and location per contact. For all known values across merged profiles, use get_contact or pass include_all_emails: true.
  • Order is newest first by id descending. Cursor pagination uses id as the cursor key.
  • Empty filter slots are rejected. Filtering on profile_field_19 when slot 19 has no label returns a validation error rather than silently returning zero rows.
  • not_equal_to / not_contains exclude unset values. Contacts where the field is unset are not included. Add a separate unknown condition if you need to capture those.