Skip to main content
Every V3 tool call names the Apostra account it runs in. Send accountId on every call, reads and writes alike, including when you can reach only one account. A call that names its account neither reads nor changes the connection’s stored selection, which stays only as a fallback for older calls until removal (see below).
A model follows one rule more reliably than two. The tool list marks accountId required on every tool except get_status (optional there) and two writes, named below. Its description is “Apostra accountId this call runs in, from get_status.” Two writes list it as optional for now, because their accountId used to name the thing being written: save_account (the child account to edit) and save_directed_campaign_subscription (the account at the outside ad platform). On those, send accountId beside the renamed input (id or providerAccountId); an accountId sent without it is still read the old way until the old shape is removed. A save_account call that creates an account (it carries accountType) never carried the old meaning, so there accountId is always the account the call runs in. Send it on every create, with organizationId when the new account belongs to an Organization other than the one the call runs in.

Get the account ID from get_status

Call get_status with no accountId. If you can act in several accounts, it lists them in accounts, by name, with each account’s accountId and kind. If you can act in one, it returns that account’s status. Call it with an accountId to read that account’s identity, readiness, blockers and next actions. A long list is paged: send the nextCursor it returns as cursor. See Account access for the fields. If you are not sure which account the person means, ask them. Do not guess between accounts, and do not pick the first one on the list. Your agent should remember the account the conversation settled on and send it on every later call.

One conversation can work across accounts

Each call runs in the account it names, for that call only. Two calls in the same conversation can name different accounts, so you can read a Buyer Account and a Seller Account side by side by naming each one per call. A named call stores nothing and does not change the connection’s stored selection, so it never moves another conversation on the same connection. Two conversations can work in two different accounts at the same time.

Naming an account never grants access

accountId says which account you mean. The server still decides whether you may act there, using the same checks as before: your membership in the account or an administrator role on its parent organization, the permissions on your role, and the limits of your credential. A credential fixed to one account (WorkOS user and organization API keys, machine credentials, buyer agents and API keys with no user behind them) can name only that account, and get_status lists no other it can name. A buyer agent reaches an account its organization’s grants cover by naming that account’s advertiser in advertiserId, never by accountId; get_status lists those accounts with nameWith: "advertiserId". An Apostra staff member who is a member of the account, or an administrator of its organization, acts there with that role, the same as in the web app. One who names an account they are not a member of gets the platform support access that applies to that account and nothing more.

Errors

ACCOUNT_NOT_REACHABLE repeats the number you sent and looks up nothing from it. Take the accountId from get_status, not from the error.

What still works while this rolls out

Tool lists are cached by hosts until a person reconnects, so many conversations still run on a list from before accountId was required. Until a removal date, those conversations keep working:
  • A call that omits accountId still runs, in the account your connection last switched to, or in your credential’s home account if it never switched. Its result carries one line telling you to send accountId on every call. A write from a connection that can be switched still fails with ACCOUNT_CONFIRMATION_REQUIRED.
  • expectedAccountId is no longer listed, because accountId replaces it. The server still accepts it. Send accountId instead.
  • switch_account is retired and no longer appears in any tool list. A client working from a cached list can still call it. The result says it is retired and tells you to send accountId on every call instead.
We will announce the removal date before it arrives. After it, a call that does not name its account is refused, and switch_account and expectedAccountId are removed. Do not build on the fallback.

The V3 HTTP API

A V3 HTTP request names its account the same way: accountId in the JSON body of a tool call, or the accountId query parameter when reading a write receipt or a document. The server checks it exactly as it checks the account a credential may use, and naming an account never grants access. A credential bound to one account may leave accountId out. The X-SCOPE3-CUSTOMER-ID header is deprecated. It still works until the removal date, and a request that names its account only by the header gets a Deprecation: true response header and a Link to this page. If a request sends both and they differ, it fails with ACCOUNT_MISMATCH and nothing is read or written. After the removal date a request that sends the header is refused. See HTTP API.

Inputs that were called accountId

Five inputs used accountId for a different account. They have new names, so accountId always means the account the call runs in. During the rollout, an older call that leaves out the new input keeps the old meaning of accountId on the first four, except a save_account create. open_media_partners_page has no such fallback: its accountId always names the account the call runs in. See v3 Concepts for how the server tells the two shapes apart.
  • Account access covers which account a call runs in when you name none, organization accounts and account kinds.
  • Errors covers the full V3 error envelope.
  • Quickstart shows the first get_status read.