List Contacts
Queries contacts with attribute and event filters, returning a page of contacts plus the total count matching the filter. A POST because the filter structure is too rich for a query string. This is the endpoint behind audience building. The same filter shape defines a dynamic contact list or a campaign audience.
Authorization
Authorization In: header
Path Parameters
ID of the project to list contacts from.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Property names to include on each contact. Omit for the default set. Narrowing this is the main lever for making large queries cheaper.
After Tinybird returns, keep only these property keys on the wire. Does not change the Tinybird SQL. The All Contacts table uses this so first paint is not the full identify map.
Restrict the result to these contact IDs.
When false, skip the Tinybird uniqExact count and return the page length. Use a follow-up take:0 request for the exact total.
Attribute and event conditions the contact must satisfy. Omit to match every contact in the project.
Attribute conditions, combined with oneDayEventFilters by groupType.
Contact attribute distinct id to filter on.
Attribute type. Defaults to string when omitted.
Comparison operator for the attribute value.
Value to compare the attribute against.
Event conditions over a rolling 24 hour window (not configurable). Each one is a condition in the group alongside filters, so AND, OR, and NOT apply to both. Used the same way by CRM lists, campaign audiences, workflow entry filters, and Audience Filter steps.
Analytics event name from analytics_queryEvents with groupBy action, or Sent email, Delivered email, Opened email, Clicked email, Bounced email, Complained email, or Suppressed email. Those seven read email activity for the same 24 hour window, not analytics.
performed: the contact has at least one event with this name in the last 24 hours. notPerformed: a contact in the project with no such event in the last 24 hours, including contacts with no events at all.
How the conditions in filters and oneDayEventFilters combine: AND all true, OR any true, NOT none true.
When true, the group is ANDed with $subscribed == true. Set by email sending, not the filter UI.
When true, the group is ANDed with $emailValidated != true. Set by email validation, not the filter UI. The user's AND, OR, and NOT are unchanged.
Contact property to sort by, e.g. $lastSeen or email.
Sort direction. Ignored unless orderBy is set.
Number of contacts to skip before collecting results. Deep offsets get progressively slower, so prefer narrowing the filter over paging far into a large audience.
Maximum number of contacts to return.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/projects/string/crm/contacts/query" \ -H "Content-Type: application/json" \ -d '{}'{ "count": 0, "data": [ { "id": "string", "createdAt": "string", "updatedAt": "string", "projectId": "string", "distinctId": "string", "email": "string", "toDelete": true, "properties": { "age": 0, "avatar": "http://example.com", "birthday": "string", "createdAt": "string", "description": "string", "displayName": "string", "email": "user@example.com", "firstName": "string", "gender": "string", "id": "string", "lastName": "string", "name": "string", "phone": "string", "title": "string", "username": "string", "website": "string", "$id": "string", "$lastSeen": "string", "$lastIdentifiedAt": "string", "$processedAt": "string", "$unsubscribed": true, "$subscribed": true, "$unsubscribeReason": "manual", "$unsubscribeSource": "string", "$emailValidated": true, "$lastEmailValidatedAt": "string", "$emailValidationResult": "string", "$emailScore": 0, "$stripeCustomerId": "string", "$os": "string", "$browser": "string", "$browserVersion": "string", "$screenHeight": 0, "$screenWidth": 0, "$screenDpi": 0, "$device": "string", "$userAgent": "string", "$ip": "string", "$timezone": "string", "$city": "string", "$country": "string", "$countryCode": "string", "$continent": "string", "$region": "string", "$locale": "string", "$latitude": 0, "$longitude": 0, "$referrer": "string", "$referringDomain": "string", "$initialReferrer": "string", "$initialReferringDomain": "string", "$utmSource": "string", "$utmMedium": "string", "$utmCampaign": "string", "$utmTerm": "string", "$utmContent": "string", "$initialUtmSource": "string", "$initialUtmMedium": "string", "$initialUtmCampaign": "string", "$initialUtmTerm": "string", "$initialUtmContent": "string", "$_toDelete": true, "$_emailScoreActions": "string", "property1": "string", "property2": "string" } } ], "usage": { "cost": 0, "duration": 0, "metricCount": 0 }}Get Usage
Returns metered spend for the project over a date window, broken down by day, app, and upstream service. This is the cost side of the ledger. See Get Balance Transactions for how that spend drew down the credit balance.
Get Contact
Fetches a single contact by distinct ID, including its merged property bag. Returns 404 if no contact matches.