RunDiffusion Logo
Skip to content

List tools

Page through the tools available in the platform.

On this page

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, put it on a board with Add a board node, or use its ID as the tool_id filter on Library.

GEThttps://api2.rundiffusion.com/api/v2/tools
AcceptsOAuth device flowPersonal API Access TokenCompany API Access Token

Request

Headers

AuthorizationstringRequired
Bearer token. This endpoint accepts an OAuth device flow token, a Personal API Access Token, or a Company API Access Token. See Authentication.Authorization: Bearer eyJhbGciOi…

Every parameter is optional.

Query

cursorstringoptional
Opaque pagination token. When a response has has_more true, pass its next_cursor here. Do not construct or parse one.https://api2.rundiffusion.com/api/v2/tools?cursor=eyJ2IjoxLCJr…
limitintegeroptionaldefault 100
Page size, from 1 to 100.https://api2.rundiffusion.com/api/v2/tools?limit=25
tool_tagstringoptional
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.https://api2.rundiffusion.com/api/v2/tools?tool_tag=9QmTz4…

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

dataarray
The tools on this page. See Tool object below.
has_moreboolean
Whether more pages exist beyond this one. Branch on this when paging.
next_cursorstring | null
Pass this back as cursor to fetch the next page. Null on the last page.
last_cursorstring | null
Echoes the cursor you sent on this request. Null on the first page. It points backwards, so paging with it loops.

Tool object

idstring
The tool ID, a 20-character opaque string. Pass it as tool_id when adding a board node, or as the tool_id filter on Library.
namestring
Display name. Can contain emoji.
descriptionstring | null
One-line summary of what the tool does.
avatar_urlstring | null
The tool's picture, as a png URL you can render directly. Null when the tool has no avatar.
average_gen_in_secondsinteger | 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_tagsarray
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_typestring
COST is deducted from the account balance. FREE is not.
tokens_per_resultinteger
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 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

401UNAUTHENTICATED
Missing, malformed, or expired token.
429RATE_LIMITED
Too many requests. Back off and retry per the Retry-After header. See Rate limits.

See Errors for the full envelope and the code list.

View as Markdown