> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Run and credit tools

> Estimate the credits a run would use, list and read runs, and check the team credit balance through MCP before and after you start paid work.

> [!NOTE]
>
> See [Filter Compatibility](https://docs.qwairy.co/mcp/tools/filters.md) for the authoritative filter contract and the coverage of every MCP tool.

These tools read run status and credits. They change nothing and use no credits. Starting a run is a write operation: see [Run write tool](https://docs.qwairy.co/mcp/write/runs.md).

They follow MCP read access and are available from Starter, without a write scope.

## estimate\_run

Estimate the credits a run would use, without reserving or debiting anything.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `brandId` | string | Yes | The brand ID from `list_brands` |
| `promptIds` | string\[] | No | Prompts to include. Defaults to the active prompts of the workspace |
| `modelIds` | string\[] | No | Models to include. Defaults to the workspace monitoring models |

### Returns

| Field | Description |
| - | - |
| `promptCount`, `modelCount`, `answerCount` | Usable target counts |
| `estimatedCredits` | Total cost of the usable prompt and model combinations |
| `availableCredits` | Balance observed at estimate time, for Managers and Owners; `null` for other roles |
| `sufficientCredits` | Whether that balance covers the estimated cost |
| `unsupportedModels` | Requested models excluded because they are unknown, disabled or unavailable in the workspace market |

An estimate is a snapshot. Starting the run revalidates the targets and the balance, so its result can differ.

### OAuth scope

Requires: `read:prompts`

***

## list\_runs

List recent runs of a workspace with their status, from newest to oldest.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `brandId` | string | Yes | The brand ID from `list_brands` |
| `limit` | integer | No | Runs per page, from 1 to 20 |
| `cursor` | string | No | Opaque `nextCursor` from the previous response. An invalid cursor is rejected |

### Returns

Each run includes its purpose, the number of prompts and models, the requested and planned counts, a computed `status`, outcome `counts` and `progressPercentage`. The response also returns `nextCursor` (`null` when there is no further page), `totalCount` and `activeCount` for the whole workspace.

Status is one of `QUEUED`, `PROCESSING`, `COMPLETED`, `COMPLETED_WITH_WARNINGS`, `FAILED`, `CANCELLED` or `NO_WORK`. Progress does not guarantee that every requested answer succeeded: read the status and the outcome counts.

### OAuth scope

Requires: `read:prompts`

***

## get\_run

Get the status and counts of one run.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `brandId` | string | Yes | The brand ID from `list_brands` |
| `runId` | string | Yes | Run ID from `start_run` or `list_runs` |

### Returns

Planning metadata for the run: its purpose, the prompt and model counts, the requested and planned counts, the number of recorded attempts, whether planning completed or failed, and timestamps. Planning completion does not mean every answer has finished: use `list_runs` for the computed status and progress.

### Example prompts

```text theme={null}
How much would it cost to run all my active prompts now?
```

```text theme={null}
Is the run I started finished?
```

### OAuth scope

Requires: `read:prompts`

***

## get\_credits

Get the credit balance of a team, its recent use and its runway.
Requires the Manager or Owner role in that team.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `teamId` | string | Yes | Team ID, from the `team` object returned by `list_brands` |

### Returns

| Field | Description |
| - | - |
| `balance` | Current credit balance |
| `usedLast30Days` | Credits used over the last 30 days |
| `averageDailyBurn` | Average credits used per day |
| `runwayDays` | Estimated days the balance lasts at the current rate, or `null` when nothing is being used |
| `subTeams` | Balances of the sub-teams this token may use, for a parent organization, otherwise `null` |

### OAuth scope

Requires: `read:brands`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.