How it works
Ids, lists, times, retries, rate limits and versions.
Ids
Every id starts with what it is: rec_ a recording, tdo_ a to-do, cal_ a calendar event, wsp_ a workspace, whe_ a webhook endpoint, evt_ an event, key_ a key, req_ a request. They sort by time. Speakers are sp_1, sp_2… within a recording, in the order they first speak.
Store your own ids on a recording with client_reference_id (one per workspace) and metadata (up to 20 keys of your own), then find it again with ?client_reference_id= or ?metadata[deal_id]=4471.
Lists
Lists answer a page at a time:
{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "eyJ2Ijoi…" }Pass limit (1 to 100, 20 by default) and cursor (the next_cursor you were given). Pages hold steady while data changes underneath, so a list is never skipped or repeated.
Syncing: keep the newest updated_at you've seen and ask GET /v1/recordings?updated_after=<it>. Lists then run oldest change first.
Times
Times are ISO 8601 in UTC (2026-11-03T09:30:00.000Z). Filters take a day (2026-11-03) or a full time. Lengths are in milliseconds (duration_ms), money in US dollars.
Retrying safely
Send an Idempotency-Key header (any unique string, a UUID say) with a POST, PATCH or DELETE. If the connection drops and you send it again with the same key, you get the first answer back, marked Idempotent-Replayed: true, and a paid call is never charged twice. Keys are kept 24 hours. The same key with a different request answers 409 idempotency_key_reused.
Changes from the app
PATCH a recording with If-Match: <its updated_at> and, if someone changed it in Taad meanwhile, you get 412 version_conflict instead of overwriting their change.
Rate limits
300 requests a minute for a personal key's owner, 600 for an organization, all its keys together. Every answer says where you are:
| Header | What |
|---|---|
RateLimit-Limit | requests allowed a minute |
RateLimit-Remaining | left in this minute |
RateLimit-Reset | seconds until it fills again |
Retry-After | on a 429: wait this many seconds |
Versions
/v1 only grows: new fields and new calls arrive without notice, so ignore fields you don't know. Anything that would break your code would come as /v2, with a year of overlap and plenty of warning.
Errors
One shape for every error, with a message that says what to do next. See Errors.