Export an ad-hoc audience as CSV
Resolve an ad-hoc audience — an unsaved segment filter AST, the same shape the segment builder and POST /api/v1/segments/auto-suggest produce — live against the tenant’s contacts and download the matched rows as an RFC-4180 CSV attachment, without first persisting or materialising a segment. PII columns (phone, email) honour the caller’s role + reveal context. Requires the contacts:write scope (owner / admin / developer). Hard-capped at 50,000 rows; a truncated export sets the X-Export-Truncated: true response header. The saved-segment equivalent is GET /api/v1/contacts/segments/{id}/export.csv.
Authorizations
Dashboard JWT token from Clerk
Body
The audience definition — the same FilterAst the segment builder and auto-suggest speak (a single condition or a nested AND/OR group). Validated server-side against the field allowlist + depth cap.
Optional row cap below the 50,000-row hard ceiling (e.g. for a quick sample). Clamped server-side.
1 <= x <= 50000Optional filename stem for the download. Sanitised so it cannot break the Content-Disposition header.
120Response
RFC-4180 CSV download (Content-Disposition: attachment). One row per matched contact, with a header row: contact_id, first_name, last_name, email, phone, country_code, lifecycle_stage, tags, created_at.
One flat row per matched contact, with a header row.