> For the complete documentation index, see [llms.txt](https://docs.avastudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avastudio.com/api-and-mcp/tools/account.md).

# Account

Check the key and follow long-running jobs.

### whoami

Check the API key and see the account: user id, credit balance, brands and starter-credit status. May claim an eligible account’s one-time starter grant when that rollout is enabled. Call this first in a session; if brands is empty, call brand\_create next.

* **Permission:** Account (`account:read`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/whoami`

#### Input

No input: send `{}`.

#### Output

| Field                             | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `user_id`                         | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `email`                           | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `credits_balance`                 | number           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `key_budget`                      | object           | This key's (or connection's) API spend this UTC month against its monthly credit limit.                                                                                                                                                                                                                                                                                                                                                                            |
| `key_budget.month`                | string           | UTC month the numbers cover, YYYY-MM.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `key_budget.credits_used`         | number           | Credits this key used this month: the API credits it charged, including holds of jobs still running, and, on a key with a monthly limit, the media credits creative\_produce, broll\_create and the Studio generation tools spent (their media estimate while running, replaced by their media\_credits\_charged, at most the estimate, once the production is ready or has definitively failed). A key without a limit counts API credits only. Value at least 0. |
| `key_budget.monthly_credit_limit` | number or null   | The key's monthly credit limit; null = no limit. A call that would pass it fails with budget\_exceeded.                                                                                                                                                                                                                                                                                                                                                            |
| `connection`                      | object           | Set when the caller signed in with Ava (OAuth) instead of using an API key: the connected app. key\_budget is then this connection's budget.                                                                                                                                                                                                                                                                                                                       |
| `connection.app`                  | string           | The connected app's name, as it registered (e.g. ChatGPT, Claude).                                                                                                                                                                                                                                                                                                                                                                                                 |
| `connection.verified`             | boolean          | True when Ava recognizes the app by its redirect domain (ChatGPT, Claude). Unverified apps can still connect.                                                                                                                                                                                                                                                                                                                                                      |
| `brands`                          | array of objects |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `brands[].brand_id`               | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `brands[].name`                   | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `brands[].is_primary`             | boolean          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `starter_credits`                 | object           | The account’s one-time starter grant, included in credits\_balance; unspent credits expire at expires\_at.                                                                                                                                                                                                                                                                                                                                                         |
| `starter_credits.status`          | string           | One of `active`, `expired`, `converted`.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `starter_credits.granted_credits` | number           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `starter_credits.granted_at`      | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `starter_credits.expires_at`      | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `starter_credits.days_left`       | number           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `next_steps`                      | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                                                                                                                                                                                                                          |

### jobs\_get

Check a job from any tool that returns a job\_id; its kind is the tool's name. Poll every few seconds until status is succeeded or failed: result holds the tool's output (failed project\_ask jobs can also retain partial results), credits\_charged the API credits it cost and media\_credits\_charged the media credits its generation spent (while running: credits\_held and media\_credits\_estimate).

* **Permission:** Any key
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/jobs_get`

#### Input

| Field    | Type   | Required | Description                      |
| -------- | ------ | -------- | -------------------------------- |
| `job_id` | string | Yes      | Job id from a long-running tool. |

#### Output

| Field                    | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `job_id`                 | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `kind`                   | string           | One of `brand_create`, `brand_media_add`, `broll_create`, `draft_briefs`, `draft_iterate`, `meta_sync`, `draft_clone`, `plan_run`, `concepts_draft_more`, `creative_produce`, `project_edit`, `project_ask`, `export_render`, `ava_ask`, `image_generate`, `video_generate`, `audio_generate`, `video_upscale`, `video_remove_background`, `image_reframe`, `image_layerize`, `project_from_template`, `scene_generate`, `captions_generate`, `library_add`. |
| `status`                 | string           | One of `queued`, `running`, `succeeded`, `failed`.                                                                                                                                                                                                                                                                                                                                                                                                           |
| `progress`               | object           | Present while queued or running, when the job reports it.                                                                                                                                                                                                                                                                                                                                                                                                    |
| `progress.stage`         | string           | Machine-readable step name.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `progress.label`         | string           | Short human-readable status line.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `result`                 | any              | Present when status is succeeded. Shape depends on kind (see the tool's job result).                                                                                                                                                                                                                                                                                                                                                                         |
| `error`                  | object           | Present when status is failed.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `error.code`             | string           | One of `unauthorized`, `forbidden`, `not_found`, `invalid_input`, `insufficient_credits`, `budget_exceeded`, `conflict`, `rate_limited`, `upstream_error`, `not_configured`.                                                                                                                                                                                                                                                                                 |
| `error.message`          | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `error.hint`             | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `error.retry_after_sec`  | number           | Seconds until a rate-limited call may be retried.                                                                                                                                                                                                                                                                                                                                                                                                            |
| `error.request_id`       | string           | Id of the request that failed (REST: also the x-request-id response header; a failed job: the request that started it). Quote it when you report a problem to Ava support.                                                                                                                                                                                                                                                                                   |
| `credits_held`           | number           | Paid jobs, while queued or running: the credits the API reserved for this job. Value at least 0.                                                                                                                                                                                                                                                                                                                                                             |
| `media_credits_estimate` | number           | While queued or running, for jobs whose media Studio's pipeline makes: the media credits it is expected to charge, not held by the API; once finished, media\_credits\_charged says what it charged. Value at least 0.                                                                                                                                                                                                                                       |
| `credits_charged`        | number           | Paid jobs, once finished: API credits charged; 0 when the hold was released (a failed job is not charged). Media credits the generation pipeline charges are not included: see media\_credits\_charged. Value at least 0.                                                                                                                                                                                                                                    |
| `media_credits_charged`  | number           | creative\_produce, broll\_create and the Studio generation tools (image\_generate, video\_generate, scene\_generate, ...), once finished (failed ones too, when the generation spent): media credits the generation pipeline charged to the balance for this job, on top of credits\_charged. creative\_produce on a paid campaign: updated when Studio's post-delivery review, which may repair and spend more, finishes. Value at least 0.                 |
| `created_at`             | string           | ISO-8601 timestamp                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `updated_at`             | string           | ISO-8601 timestamp                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `next_steps`             | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                                                                                                                                                                                                                    |
