Tables
Workspace tables: lists every agent shares between sessions, merged by identity, with a suppression list and a repeat-send guard on every send, and enrichments saved into rows never bought twice.
A table is a list your workspace keeps between sessions: the leads a campaign enriches, the creators you are about to message, the companies you monitor. Every agent on the workspace reads and writes the same rows (Claude Code, Codex, a claude.ai or ChatGPT connector, a teammate's agent, a scheduled routine), so a routine can pick up where the last session stopped without a CSV on anyone's disk.
A row is JSON you shape. RouterGrowth adds four things on top:
- Identity. Every row is keyed on a person (email, then LinkedIn URL, phone, or a handle with its platform, such as
instagram:janedoe), in a company table on a domain, or on a column you choose. Writing the same person twice merges into one row, whichever identity you name them by. - A suppression list. Anyone on it is never sent to again, on any channel a row ties them to. The check runs on the server before every send.
- Touches. Every successful send is recorded and stamps the rows of the people it reached (
touches,last_touch_at,last_touch_channel). - Saved results. An enrichment saved into a row is not bought again: a repeat of it in the last 30 days is answered from the row for free.
Tables are free to use, within a quota set by the workspace's plan:
| Plan | Rows per workspace | Tables |
|---|---|---|
| Pay per call | 25,000 | 20 |
| Starter | 50,000 | 50 |
| Plus | 100,000 | 100 |
| Pro | 500,000 | 100 |
| Scale | 2,000,000 | 500 |
One table holds at most 50,000 rows, and one row at most 16 KB of data. A write that would pass a quota answers 413 payload_too_large and writes nothing; an upserted row over 16 KB is refused on its own (see refused below).
Turn tables on
Tables are off until a workspace turns them on, and a workspace with them off works exactly as before: no table tools, no suppression or repeat checks on its sends. Turning them on changes how sends behave (suppressed people and repeat first messages are blocked), so it is a choice the workspace makes.
GET /v1/features {"tables": {"enabled": false, ...}}
POST /v1/features {"tables": true} on; false turns them off again
Or routergrowth features --enable tables, or the switch on the dashboard's Settings page. Turning them on also indexes the workspace's earlier sends, so the repeat guard knows who was already contacted. Turning them off keeps your tables and suppression list but stops using them. Until tables are on, every route below answers 403 forbidden, and a run that passes record or into is refused before anything is spent.
Nobody has to ask for a table
Agents create them as a side effect of the job. The rules they follow ship in the MCP server instructions of a workspace with tables on:
- A list you will enrich, contact, monitor or hand over goes in a table. A one-off lookup does not.
- Name it after the job,
skincare-creators-fr, with a one-line description, and tell the user the name once. - The first write creates it: a run with
into, or an upsert. - Start every session with
tables(free) and resume an existing table instead of starting a new one.
Write rows
POST /v1/tables/{name}/rows
curl -X POST https://api.routergrowth.com/v1/tables/skincare-creators-fr/rows \
-H "Authorization: Bearer $ROUTERGROWTH_API_KEY" -H "Content-Type: application/json" \
-d '{"description": "French skincare creators, 10k to 100k followers",
"rows": [{"platform": "instagram", "handle": "janedoe", "followers": 22000, "status": "found"},
{"name": "Lee Park", "email": "lee@acme.com", "linkedin_url": "https://www.linkedin.com/in/leepark"}]}'
Up to 500 rows per call. status and next_at are row fields, everything else is data. New values win, and empty ones never erase what a row holds ("mode": "replace" swaps the whole object instead). A top-level status in the body applies to the rows this call creates (default new); title, description, key and columns apply when the call creates the table.
{"table": "skincare-creators-fr", "created": true, "inserted": 2, "updated": 0, "unchanged": 0,
"merged_in_call": 0, "conflicts": [], "refused": [],
"keys": {"inserted": ["instagram:janedoe", "lee@acme.com"], "updated": []},
"also_in": [{"table": "beauty-q3", "count": 1, "by_status": {"sent_j0": 1}, "contacted": 1}],
"hints": ["1 of these are already in 'beauty-q3', 1 of them contacted."]}
also_in names the other tables that already hold the same people. merged_in_call counts rows that named the same person as an earlier row of the same call. refused rows (with their index and reason) carry no identity the table keys on, too much data, or an invalid status or next_at. conflicts are rows whose identities point at two different existing rows: nothing is written for them.
Query rows
GET /v1/tables/{name}/rows?status=approved&due=true&fields=email,first_name&limit=50
POST /v1/tables/{name}/rows/query
{"status": ["sent_j0"], "due": true,
"where": {"email_status": "valid", "followers": {"gte": 10000}, "phone": {"exists": false}},
"fields": ["email", "first_name", "j0_message_id"], "order": "-followers", "limit": 50}
The GET form takes status and fields as comma-separated lists, plus due, order, limit and cursor; filters on data fields need the POST form. where takes a value for equality or {op: value} with eq, ne, in, nin, exists, empty, contains, gt, gte, lt, lte. Numbers compare as numbers, even when stored as strings; dotted paths reach nested fields (profile.followers). The row fields status, next_at, touches and last_touch_at filter the same way, with times as ISO or relative (-7d). due: true keeps rows whose next_at has passed. order names a field, - first for descending. Pages are 50 rows by default and 500 at most; pass next_cursor back as cursor. Keep fields short: a routine polling a table should not pull every column each time.
The answer carries total, next_cursor and rows. A row is {row_id, key, status, next_at, touches, last_touch_at, last_touch_channel, suppressed, data, updated_at}, plus saved once a run's result was saved into it: the capabilities those results came from.
GET /v1/tables every table with row counts by status, and the quota
GET /v1/tables/{name} counts by status, rows due, columns with fill rates, the latest rows
Update, claim and delete
PATCH /v1/tables/{name}/rows
{"status": "approved", "limit": 30, "if_status": "approved", "set": {"status": "sending"}}
set holds status, next_at (ISO or +4d, +12h) and data fields; a null removes a field. Name rows with keys (a row's key or row_id, or any email, URL or platform:handle it carries), or with a filter and a limit (500 at most). With if_status the status change is a claim: only rows still in that status change, and the answer lists exactly those (skipped counts the rest), so two routines running at once never take the same rows.
POST /v1/tables/{name}/rows/delete {"keys": [...]} or a filter with limit
DELETE /v1/tables/{name}/rows/{key}
DELETE /v1/tables/{name}?confirm=true the table and its rows, for good; suppressions stay
PATCH /v1/tables/{name} title, description, columns, rename
POST /v1/tables create up front: {"name", "title", "description", "columns", "key": "auto|domain|email|linkedin|phone|handle|field:<name>"}
An unknown table answers 404 not_found; creating or renaming to a name already taken answers 409 conflict. Names are stored lowercase, with dashes for anything but letters and digits.
Link runs to rows
Two fields on run (and batch_run over MCP) connect the paid calls to the table. They work on capabilities, not on raw endpoints.
into lands a list result as rows; social.profile lands its one profile, and a capability without a list result is refused before anything runs (the error lists the ones that take into). Posts and comments become their authors, one row per creator with up to 5 of their matching posts kept under signals; people and companies merge by identity, so a row already there keeps its status. A table that does not exist yet is created, keyed on the records' own identity when they are not people or companies. Watches take into too: every refresh lands its records, the new ones as new rows.
{"capability": "social.search", "input": {"platform": "instagram", "query": "routine skincare", "limit": 50},
"routing": {"max_cost": "0.60"}, "into": {"table": "skincare-creators-fr", "status": "found"}}
record links a run to one row. On success set updates the row and save copies result fields into it ("all", or {"result field": "row field"}); on a no_match on_miss applies; a failed run leaves the row as it was. An unknown table or key fails before anything runs. A send linked to a row is also checked against every identity the row carries.
curl -X POST https://api.routergrowth.com/v1/run \
-H "Authorization: Bearer $ROUTERGROWTH_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: skincare-creators-fr:lee@acme.com:j0" \
-d '{"capability": "email.send",
"input": {"inbox_id": "hello@yourdomain.com", "to": ["lee@acme.com"], "subject": "...", "text": "..."},
"routing": {"max_cost": "0.01"},
"record": {"table": "skincare-creators-fr", "key": "lee@acme.com",
"set": {"status": "sent_j0", "next_at": "+4d"},
"save": {"message_id": "j0_message_id", "thread_id": "j0_thread_id"}}}'
Give every send tied to a row the idempotency key <table>:<key>:<step> (the Idempotency-Key header over REST, idempotency_key on the MCP run tool): a routine retried after a crash replays the send instead of sending twice. The run's answer carries a table object with what was written.
Enrichments are not bought twice
When an enrichment (contact.find, contact.phone, person.enrich, company.enrich, company.funding, company.technologies, social.profile) was saved into a row of the workspace with record or into in the last 30 days, the same enrichment for the same subject is answered from that row: status succeeded, charged nothing, no provider called, and a source naming the table, the row and the run it came from. It works across agents and tables, and for the subject rather than the exact input (first name Jane or jane, domain acme.com or https://acme.com: the same contact.find). Pass routing.fresh: true to buy it again, or pin a provider with routing.provider.
Suppressions
GET /v1/suppressions?kind=email&reason=bounce
POST /v1/suppressions {"subjects": ["jane@acme.com", "spam.io", "instagram:bob"], "reason": "unsubscribe"}
POST /v1/suppressions/remove {"subjects": ["jane@acme.com"]}
Subjects are emails, domains (every address on them), LinkedIn URLs, phones and platform:handle (or @handle with platform), up to 500 a call. Reasons: unsubscribe, bounce, complaint, not_interested, manual (the default). A send to a suppressed person comes back 403 suppressed, is kept as a blocked run, and charges nothing. When a row ties an email to a LinkedIn profile, suppressing either blocks both. Nothing is added to the list for you: an email.bounced or email.complained event, or a reply asking to stop, is the cue to suppress. Remove a suppression only when the person asked to hear from you again.
Repeat first touch
A new conversation with someone the workspace already contacted on the same channel in the last 30 days comes back 409 repeat_touch, blocked and not charged, naming the earlier run. The channels are email (email.send and gmail.send count as one), LinkedIn invitations, LinkedIn messages, Instagram messages and WhatsApp messages. Replies in a thread pass (in_reply_to for email, chat_id for LinkedIn, Instagram and WhatsApp), and so do your own addresses, where test sends go. With the user's say-so, routing.allow_repeat: true sends anyway.
GET /v1/outbound-guard
POST /v1/outbound-guard {"repeat_touch_days": 14} up to 365; 0 turns it off
CSV
GET /v1/tables/{name}/export.csv
POST /v1/tables/{name}/import?status=new the CSV as the body, first line the column names
The export's first columns are key, status, next_at, touches and last_touch_at, then the data fields. Import upserts with the same rules as a write, 1 MB at most (about 5,000 rows): status and next_at columns become row fields, key, touches and last_touch_at are ignored, and the table is created if it does not exist, so a leads.csv from an earlier campaign becomes a table in one call.
Tools
Over MCP, once tables are on (the tools are not listed before): tables reads (no arguments to list, table to describe, filters to query rows, suppressions: true for the list) and table_write writes (action: upsert, update, delete, create, edit, drop, suppress, unsuppress). Both are free. run and batch_run also take record, into and allow_repeat.
Reading this as an agent? This page as markdown: /docs/api/tables.md · every page: /docs/llms.txt