Lists API

A List is a saved, named set of companies scoped to your organization. A list is built from a definition — a boolean filter tree (the same tree the web app’s list builder edits) — plus any domains you add or exclude by hand. When you read a list’s members, Trace materializes the definition into a concrete set of companies, caches the result, and serves it back to you in tiers (high / medium / exploratory).

Typical lifecycle:

1. Create an empty list (or seed it with an initial definition).
2. Define it — write or edit the filter tree, or add domains directly.
3. Materialize — read the members; Trace recomputes when the definition changed.
4. Share — grant other users in your org viewer or editor access.

User-scoped key required

Every Lists endpoint requires a user-scoped credential: a user API key. Org-scoped API keys are rejected with 403 user_credential_required. Lists carry per-user ownership and permissions, so identity must resolve to a single user. See /authentication/.

All paths are under the production base URL https://api.tracedata.ai.

Core endpoints

These are the main flows. The full set (around 25 endpoints, including definition version history, audit log, excluded-domain management, and company search) is in the API reference.

List CRUD

Method	Path	Purpose
POST	/v1/lists	Create a list (optional initial definition)
GET	/v1/lists	List the lists you can see, with your access_level
GET	/v1/lists/{list_id}	Read one list, including its definition and permissions
PATCH	/v1/lists/{list_id}	Rename a list
DELETE	/v1/lists/{list_id}	Delete a list

Note

The list description is system-owned — it’s derived from the filters, so any description you send on create is ignored.

Definition and filtering

Method	Path	Purpose
GET	/v1/lists/filter-fields	The catalog of filterable fields, operators, and a registry_version to stamp into your definition
POST	/v1/lists/preview-count	Preview the member count for a (possibly unsaved) definition tree
GET	/v1/lists/{list_id}/definition	Read the active definition tree
PUT	/v1/lists/{list_id}/definition	Replace the definition (appends a new version, invalidates the materialization cache)

Members and materialization

Method	Path	Purpose
GET	/v1/lists/{list_id}/members	Read members (paginated; limit, offset, tier, search_name_or_domain, force_refresh)
POST	/v1/lists/{list_id}/materialize	Force a recompute and return per-tier counts
GET	/v1/lists/{list_id}/export.csv	Download all members as CSV (credit-charged)
POST	/v1/lists/{list_id}/domains	Add one or more domains to the list
DELETE	/v1/lists/{list_id}/domains/{domain}	Remove a domain

CSV export is metered

GET /v1/lists/{list_id}/export.csv bills credits — one credit per net-new company unlocked in the last 30 days. See /credits/. An exhausted balance returns 402 before any rows are sent. Over-cap exports are truncated and set the X-Export-Truncated response header.

Permissions

Method	Path	Purpose
GET	/v1/lists/{list_id}/permissions	List who can access the list
POST	/v1/lists/{list_id}/permissions	Grant editor or viewer access (per-user or org_wide)
DELETE	/v1/lists/{list_id}/permissions/{permission_id}	Revoke access
POST	/v1/lists/{list_id}/owner	Transfer ownership

Worked example: create, define, read

Create an empty list, give it a definition, then read the members.

1. Create a list

curl -X POST https://api.tracedata.ai/v1/lists \
  -H "X-API-Key: $TRACE_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Shopify stores hiring engineers"}'

The response includes the new list_id and the (empty) definition. Next, write a definition tree. Fetch GET /v1/lists/filter-fields first to learn the exact field keys, operators, and the current registry_version to stamp in.

2. Set the definition

curl -X PUT https://api.tracedata.ai/v1/lists/123/definition \
  -H "X-API-Key: $TRACE_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d @definition.json

A malformed or unbounded tree returns 422. On success the definition version bumps, which invalidates the cached members so the next read recomputes.

3. Read the members

curl "https://api.tracedata.ai/v1/lists/123/members?limit=50&tier=high" \
  -H "X-API-Key: $TRACE_USER_API_KEY"

To skip the cache and recompute on demand, pass force_refresh=true, or call POST /v1/lists/{list_id}/materialize to force a recompute and get back the per-tier counts (total_count, high_count, medium_count, exploratory_count).

Preview a count without saving

POST /v1/lists/preview-count evaluates a definition tree and returns {count, capped} without touching any saved list — useful for showing “how big would this list be?” while a user edits filters. capped: true means the real count is at or above the preview ceiling (render it as “10,000+”).

curl -X POST https://api.tracedata.ai/v1/lists/preview-count \
  -H "X-API-Key: $TRACE_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d @definition.json

Errors

• 403 user_credential_required — you used an org key. Lists need a user key.
• 404 — the list doesn’t exist, or you can’t see it (collapsed on purpose so callers can’t probe for list IDs).
• 422 — the definition tree is malformed or unbounded.
• 409 — a concurrent edit bumped the definition version mid-operation; re-read and retry.

See /errors/ for the shared error shape.

Try it in the reference

The interactive API reference documents every Lists endpoint, the full request and response schemas (including the definition-tree shape, audit log, and version history), and lets you call them with your own key.