get_account
by the PREVIZ team
Read this connection's access
What it does
What this credential may do: how it signed in, its scopes, the projects it is limited to, its monthly credit cap and this month's spend through it, its live spending agreement's remaining budget and expiry, how many projects it reaches, until when a deprecated confirm:true still runs, its call-rate and parallel-run limits, the calls it has left right now, the paid runs it holds in flight, each engine lane's own per-minute pace, and — the one answer a frozen credential still gets — whether it is frozen and where a person lifts it. Free, <300 ms.
- Access class
read· Reads only; changes nothing and costs nothing.- Cost
- Free.
- Project
- Not tied to one project.
A key holds only the access classes its owner gave it, set in Account → API keys → the key's Access: a new key holds read and write, and spend needs a monthly credit cap. tools/list shows only the tools a key holds, and a call to any other is refused with INSUFFICIENT_SCOPE. A key made before access classes existed keeps what it could do then (read, write, spend and live) until its owner sets its access; produce is given, never inherited.
Price
Free. This tool never spends credits.
Arguments
dryRunboolean · optional- true: answer what this call WOULD do — the route its engines would take under the project's policy, its price in every mode, whether it writes — and run nothing: nothing is written, nothing is charged.
Unknown arguments are refused by name rather than ignored, so a misspelling never runs quietly.
Answer
The fields this tool's answer declares. They arrive as structuredContent, and as the same JSON in the first text block for clients that read text.
authKind- api_key or oauth.
label- The key's name, or the connector it was granted to.
scopes- The scopes held: read, write, spend, produce, live, webhooks. Tools needing another are not listed.
legacyKey- true for a key from before scopes: it holds every scope, on the person's own projects, until its owner sets its access.
reach- own (the person's own projects only: a key from before scopes, or a connector sign-in) or team (every project the person is on, at their role).
projectIds- The projects a key is limited to, or null for every project the person reaches.
reachableProjects- How many projects this caller reaches (up to 200 counted).
keyBudget- For a key with a monthly cap: monthlyCap, spentThisMonth, remaining.
mandate- Present for an API key holding exactly one live spending agreement: mandateId, projectIds, remaining (of its up-to), todayRemaining (of today's limit, UTC), perJobMax, tiers and expiresAt. Absent when it holds none, several (list_mandates) or they could not be read — liveMandates and mandateNote say which.
liveMandates- How many live spending agreements this key holds; null when they could not be read. Absent for a connector sign-in.
mandateNote- What the agreement lets a paid call do, or how to get one.
spendNeedsCap- true when spending outside a spending agreement needs a monthly cap that is not set yet.
confirmDeprecatedUntil- For a legacy key: when confirm:true stops working. null when it does not apply.
frozen- When a person froze this credential, its organisation or the project named (or the agent froze itself): scope, since, by, unfreezeAt, a note, and actionUrl — the PREVIZ page where a person lifts it. null when it can run. Every other tool answers FROZEN meanwhile.
limits- The brakes on this credential, the same on every plan: callsPerMinute, burst, paidRunsAtOnce, and queuedJobsAtOnce (the most jobs it may have waiting in the queue).
remaining- Calls left in this credential's bucket after this one: calls, of, fullInMs. Every answer also carries it as _meta.rateLimit and RateLimit-* headers.
paidRunsInFlight- Paid runs this credential holds right now (at most limits.paidRunsAtOnce); null when it could not be read.
queuedJobs- Jobs this credential has waiting in the queue (accepted with queue:true, not started yet; at most limits.queuedJobsAtOnce); null when it could not be read.
lanePace- Each engine lane's own pace per person per minute (takes, frames, meshes, layer splits, voice, sound effects, music, take frames) — the same on every plan.
lanePaceNote- What happens past a lane's pace.
manageAt- Where the person changes this credential's access.
Behaviour hints
The hints the tool declares to clients, so an agent can decide what needs a person's approval.
- Read-onlyYes
- DestructiveNo
- IdempotentYes
- Reaches outside PREVIZNo
Call it
The JSON-RPC message, then the same call over HTTPS. Placeholders are in capitals.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_account",
"arguments": {}
}
}curl -s https://mcp.aimpreviz.com \
-H "Authorization: Bearer $PVZ_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_account","arguments":{}}}'From an agent client you never write this by hand: connect it once (Claude Code, Cursor, TypeScript or Python) and ask for what you want.
When it fails
What the door answers instead, and what to do next. A refusal never charges.
- A call from a web page on an origin that is not allowed
- HTTP 403, JSON-RPC error -32003, before the body or the key is read. Call the door from a server, a terminal or a desktop client.
- A body that is not one JSON-RPC 2.0 message, or a batch
- HTTP 400, JSON-RPC error -32700 (unparseable) or -32600 (invalid or a batch), before the key is read. Send one message per POST with "jsonrpc": "2.0", a method and a string or number id.
- No key, a malformed key or a revoked key
- HTTP 401 with a WWW-Authenticate challenge, before any method runs, the handshake included. Stop and ask your person for a key; retrying will not help.
- An MCP-Protocol-Version header naming a version this door does not speak
- HTTP 400, JSON-RPC error -32600, naming the versions it supports. A request with no such header is accepted. Send the protocolVersion that initialize returned, or leave the header off.
- An unknown method
- JSON-RPC error -32601, "Unknown method" with the method's name. Use initialize, ping, tools/list or tools/call.
- An unknown tool
- JSON-RPC error -32602, "Unknown tool", naming tools/list. Call tools/list for the tools this door offers.
- Arguments that do not match the tool's input schema
- Protocol 2025-06-18: JSON-RPC error -32602 with the issues. Protocol 2025-11-25: a tool answer with isError set, naming each issue. Fix the named arguments. Unknown arguments are named, never ignored; confirm sent as the text "true" is refused, never coerced.
- A tool whose access class the key does not hold
- A tool answer with isError set, beginning INSUFFICIENT_SCOPE, naming the class the tool needs and the classes the key holds. Nothing ran and nothing was charged. Ask the key's owner to add it in Account → API keys → the key's Access; spend needs the key's monthly cap first.
- A refusal only a person can lift: the person's credits ran out (INSUFFICIENT_CREDITS), a monthly cap is missing or reached, a key lacks an access class, a freeze, or a spending agreement that was revoked, expired or does not cover the call
- The refusal carries actionUrl and actionLabel: the exact PREVIZ page for the person to press on, behind their own sign-in. For an agreement to sign again, the page opens with the old agreement's numbers suggested. A run answered by a job handle (a queued job, a long render) carries the same two fields on its job: get_job, list_jobs and the job's event. Nothing ran and nothing was charged. Hand the person actionUrl as it is. After they act, send the same call again with the same quoteToken or idempotencyKey. Two cases take a new idempotencyKey instead: a key whose first call already ran under an earlier agreement, and a queued job that has ended.
- A spend sent with your own idempotencyKey by an API key that has neither a monthly credit cap nor a signed spending agreement covering the call
- A tool answer with isError set, beginning CAP_REQUIRED, with actionUrl (the key's cap) and agreementUrl (the signing page). It is answered before anything is written, so the idempotencyKey is not used up. Nothing ran and nothing was charged. Hand the person either page. Once they have set a cap or signed an agreement, send the same call again with the same idempotencyKey.
- A webhook endpoint whose URL is not https on port 443, carries a user name, or resolves to a private address; or a call for an endpoint this key did not subscribe
- A tool answer with isError set, beginning URL_REFUSED (subscribe_webhook; nothing was subscribed), WEBHOOK_NOT_FOUND, WEBHOOK_INVALID (an unknown event kind) or WEBHOOK_LIMIT (ten endpoints per key). Give a public https URL that answers 2xx itself (a redirect is never followed), name kinds or families from the subscribe_webhook reference, and read list_webhooks for this key's endpoints.
- A replay that cannot be made exactly: a job whose request is no longer kept, a tool that changed shape, a policy that now leaves it no engine, or stale work that changed since its quote
- A tool answer with isError set, beginning REPLAY_UNAVAILABLE and saying which. Nothing ran and nothing was charged; PREVIZ never runs it on a different engine or from a guess. For replay_stale, call it again for a new plan and quote. For replay_job, call the tool yourself with the arguments you want.
- A tool that a rule for agents says is never run: the organisation's rule, or the person's own
- A tool answer with isError set, beginning GOVERNANCE_DENIED, naming whose rule it is. The call is refused before its arguments are read: nothing was priced, run or charged. get_governance lists every rule that binds this credential. An owner or admin changes the organisation's rule in PREVIZ; a person changes their own in their account.
- resume_chain on a chain that cannot carry on: cancelled, ended, past its quote, or stopped on a step that was charged or has used its attempts
- A tool answer with isError set, beginning CHAIN_STATE (or CHAIN_NOT_FOUND for a chain this credential did not start). Nothing ran and nothing was charged. replay_job on the chain's jobId quotes the same chain afresh; get_job reads what the chain already made.
Related
Concepts
Also in read
list_projectsget_boardboard_queryscene_graphlist_identitiesprovenance_reportread_driftplan_quotelist_footagelist_looksget_shot_sheetlist_meshesget_engine_policyexplain_routelist_voicesget_castbrain_searchbrain_contextask_brainlist_decisionsget_entitystale_sincecheck_continuityplan_chainget_scriptlist_scenesget_scenelist_lockslist_revisionslist_templateslist_capabilitiessimulate_policy