# List tools

> Page through the tools available in the platform.

Canonical page: https://www.rundiffusion.com/docs/api/tools/list
Endpoint: GET /api/v2/tools
Authorization: OAuth device flow or Personal API Access Token or Company API Access Token

---

A tool bundles a model or inference pipeline with the set of inputs it accepts.
This is the catalog: everything your account can run, with the ID you pass
wherever a tool is named. Read one tool's input schema with
[Get a tool](/docs/api/tools/get), put it on a board with
[Add a board node](/docs/api/boards/nodes-create), or use its ID as the
`tool_id` filter on [Library](/docs/api/library/list).

`GET /api/v2/tools`

Authorization: OAuth device flow or Personal API Access Token or Company API Access Token

## Request

**Headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer token. This endpoint accepts an OAuth device flow token, a Personal API Access Token, or a Company API Access Token. See [Authentication](/docs/api/authentication). |

Every parameter is optional.

**Query**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cursor` | string | No | Opaque pagination token. When a response has has_more true, pass its next_cursor here. Do not construct or parse one. |
| `limit` | integer | No | Page size, from 1 to 100. Default: `100` |
| `tool_tag` | string | No | Filter to one tool tag ID. IDs, not display labels: read them from a tool's tool_tags array, or from [GET /api/v2/tool-tags](/docs/api/tool-tags/list). |

## Response

`200 OK` with a cursor page: `data` holds the tools, and `has_more` plus
`next_cursor` drive pagination.

```json
{
  "data": [
    {
      "id": "1kCVin…",
      "name": "Nano Banana 🍌",
      "description": "Fast banana-themed image generator.",
      "avatar_url": "https://rundiffusion.com/...",
      "average_gen_in_seconds": 12,
      "tool_tags": [
        { "id": "9QmTz4…", "type": "MEDIA", "label": "Video" },
        { "id": "Ld6PnQ…", "type": "MODEL_FAMILY", "label": "Kling AI" }
      ],
      "pricing_type": "COST",
      "tokens_per_result": 85
    },
    {
      "id": "7bQmDx…",
      "name": "Juggernaut Lightning Flux",
      "description": "Lightning-fast Flux variant.",
      "avatar_url": null,
      "average_gen_in_seconds": 9,
      "tool_tags": [{ "id": "9QmTz4…", "type": "MEDIA", "label": "Video" }],
      "pricing_type": "COST",
      "tokens_per_result": 3
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ2IjoxLCJr…",
  "last_cursor": null
}
```

Tool IDs are 20-character opaque strings, not readable slugs. Never construct
one, and never parse meaning out of one.

### Top level

| Name | Type | Description |
| --- | --- | --- |
| `data` | array | The tools on this page. See [Tool object](#tool-object) below. |
| `has_more` | boolean | Whether more pages exist beyond this one. Branch on this when paging. |
| `next_cursor` | string \| null | Pass this back as cursor to fetch the next page. Null on the last page. |
| `last_cursor` | string \| null | Echoes the cursor you sent on this request. Null on the first page. It points backwards, so paging with it loops. |

### Tool object

| Name | Type | Description |
| --- | --- | --- |
| `id` | string | The tool ID, a 20-character opaque string. Pass it as tool_id when [adding a board node](/docs/api/boards/nodes-create), or as the tool_id filter on [Library](/docs/api/library/list). |
| `name` | string | Display name. Can contain emoji. |
| `description` | string \| null | One-line summary of what the tool does. |
| `avatar_url` | string \| null | The tool's picture, as a png URL you can render directly. Null when the tool has no avatar. |
| `average_gen_in_seconds` | integer \| null | Typical wall-clock time for one result, from recent history. Null for a newly added tool with none yet. Useful for setting expectations in a UI. |
| `tool_tags` | array | The tool tags on this tool, each an object with id, type, and label, so you can display a name without a second request. Pass an id back as the tool_tag query parameter to filter. Deleted and RunDiffusion-internal tool tags are withheld, so this can be shorter than what the product shows internally. Empty when the tool has none. |
| `pricing_type` | string | COST is deducted from the account balance. FREE is not. One of: `COST`, `FREE` |
| `tokens_per_result` | integer | List price in whole tokens for one result. Indicative rather than a quote: an account's own free allowance can make what it actually pays lower. |

### Working with tool tags

Each entry in `tool_tags` is a whole tool tag, so a list of tools already has what it
needs to render badges. Building a filter is the other direction: you want every
tool tag that exists, including ones no tool on the current page happens to carry.
[List tool tags](/docs/api/tool-tags/list) returns the full vocabulary in one unpaged
request, grouped by type. Fetch it once, cache it, and filter with the `tool_tag`
parameter above.

## Errors

| Name | Type | Description |
| --- | --- | --- |
| `401` | UNAUTHENTICATED | Missing, malformed, or expired token. |
| `429` | RATE_LIMITED | Too many requests. Back off and retry per the Retry-After header. See [Rate limits](/docs/api/rate-limits#tools). |

See [Errors](/docs/api/errors) for the full envelope and the code list.