AI3D Studio

Get a batch’s progress

get_batch

Read-onlyIdempotent

The state of a batch and of each picture in it: queued, running, done, failed or cancelled, the job_id of its run once started (get_job gives the files), credits charged, and whether retry_batch can run it again.

Input Schema

Name	Required	Description	Default
`batch_id`	Yes	The batch id start_batch returned.

Output Schema

Name	Required	Description
`items`	Yes
`model`	Yes
`scene`	Yes
`counts`	Yes
`status`	Yes
`batch_id`	Yes
`created_at`	Yes
`item_count`	Yes
`settled_at`	Yes
`quoted_credits`	Yes	What the batch costs if every picture runs.
`charged_credits`	Yes	What its runs were charged so far.
`per_item_credits`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedOct 24, 2026
- removedOutput schema / properties / items / items / properties / error_code / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / items / items / properties / error_code / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / items / items / properties / job_id / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / items / items / properties / job_id / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / settled_at / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / settled_at / type
```
Added value: +[
+  "string",
+  "null"
+]
```
First observedOct 8, 2026

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish read-only, idempotent, non-destructive behavior, and the description builds on that by disclosing content an agent would otherwise have to discover: per-picture statuses, the job_id linkage once a run starts, credits charged, and whether a retry is possible. No auth, rate-limit, or error behavior is described, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence, front-loaded with the resource state and then the useful extras. The enumerated status list is long but earns its space by telling the agent exactly what values to expect.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description does not need to enumerate return values, yet it does so usefully and ties them to sibling tools. It omits only edge behavior such as what happens for an unknown or not-yet-started batch.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter with 100% schema description coverage, and the schema already explains that batch_id is the value start_batch returned. The description adds nothing beyond that, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names the resource (a batch) and precisely scopes what is returned: batch state plus per-picture state, with the full status vocabulary spelled out. It also distinguishes itself from get_job by noting that get_job is where the files live, so an agent can separate the two without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Placement in the workflow is clear from the mentions of start_batch's id, get_job for files, and retry_batch for re-runs, which implicitly define this as the polling/progress-inspection step. There is no explicit when-not or prerequisite statement, but the routing hints are strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All AI3D Studio tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?