# Relevance AI Tools: Steps, Webhooks and the Per-Run Action Meter

> Build Relevance AI Tools: steps, Python and API calls, branches, loops, webhook and schedule triggers, run-time limits, and why each run bills one Action.

_Source: https://professionalstoolkit.com/articles/relevance-ai-tools — The Professional's Toolkit · updated November 2026_

---

A Relevance AI Tool is a reusable chain of steps (LLM prompts, API calls, app integrations and Python or JavaScript code) that you assemble without writing a full program, then hand to an agent (which a webhook can start) or run on a schedule or through the API. The number that shapes every design choice: each Tool run bills as one Action, however many steps it holds, and a run that fails still counts [1]. Build fewer, fuller Tools. A standard Tool may run for 15 minutes, while the 24-hour Tool type stretches that to a full day. Tools fit work with a known shape.


**1 Action** — Per Relevance AI Tool run, however many steps it holds, failed runs included.



- **15 min** — Maximum run time of a standard Tool
- **24 hours** — Maximum run time of the 24-hour Tool type
- **4** — Maximum branches per Tool step


## One run, one Action: drawing the edges of a Tool

Relevance AI's docs describe a Tool as inputs, a sequence of steps and outputs, where every step can read what earlier steps produced. You can ask Invent to generate a working Tool from a plain-language description, or start from scratch and add each step yourself. The result is a single unit an agent can call, you can share as a form, or an outside system can trigger. Tools that Invent drafts may still need adjustments in the Tool Builder, so check each step before an agent relies on it.

Billing is why the edges matter. Relevance AI's own advice is to fold several steps into one Tool to save Actions, and to use smaller models for simple tasks to save Vendor Credits. Picture a lead flow split into three Tools: enrich, score, write to the CRM. By our arithmetic, at 500 leads a month that is 1,500 Actions a month, against 500 if one Tool does all three: 60% of Pro's 2,500 Actions a month versus 20%. The 1,000 Actions a month saved are the size of one Action top-up pack, priced at $80 per 1,000 Actions; at this volume both versions still fit inside Pro's allowance, so the gain is headroom before any top-up is needed.

Retries count too, so a Tool that fails twice before an agent's retry succeeds has cost three Actions. Model calls inside the steps run on a second meter, Vendor Credits, passed through at wholesale with no markup. Your own model keys cut Vendor Credit spend but not the subscription or Actions. Some steps also bill elsewhere. The Firecrawl step, for example, needs your own Firecrawl account and API key, and Firecrawl bills those credits itself.


> ⚠ **Failed runs still bill:** A Tool run that fails still counts as one Action, so every retry of an unhandled error costs another Action.


## Inputs, steps and outputs: the three parts you configure

Inputs define what a Tool accepts. The types run from text, numbers, checkboxes and dropdowns to lists, tables, JSON, knowledge tables, files, API keys and OAuth accounts, which let a user connect HubSpot, Slack or Google Sheets. For JSON inputs you can attach a JSON Schema to guide the agent, but only the properties keyword is read. When an agent uses the Tool, each input can be left for the agent to decide, set manually, or filled from an earlier tool's output. Choose that per input.

Steps do the work. The documented groups include LLM prompts, Firecrawl, website extraction through Apify or Browserless, API calls, Google Search, Python, Delay, file conversion, seven Knowledge steps, and app steps for Confluence [p1], Google Calendar, Docs and Sheets, Gmail, LinkedIn, Slack and Trello. File conversion covers PDF to text, with optional OCR for scanned files, and audio or video to text. With an Airtop account connected, browser steps can click, type, scroll, take screenshots and extract page data. Since October 2026 a Decide step brings decision models into Tools; one of them, Jev 1.13 from TypeSafe, needs your own TypeSafe API key.

The LLM step is the one most Tools lean on. It offers a fallback model, a system prompt, temperature, conversation history and a forced response format. Data that is not knowledge is capped at 131,072 tokens, roughly 90 KB, so larger material belongs in a knowledge table. Thinking tokens bill as output. By default a Tool returns the output of its last step, and everything it outputs lands in the calling agent's context, so configure outputs by hand when the agent needs only a few fields.


> 💡 **Trim what a Tool returns:** Everything a Tool outputs enters the calling agent's context, so configure outputs to return only the fields the next step needs.


## Code and API steps for everything else

When no ready step fits, code does. The Python step can install any PyPI package and runs on a Modal Labs or Daytona backend, with optional fallback to the other one. An Integration helper class handles authenticated OAuth calls, though User Level Authentication is not supported in code steps. Relevance AI's features page also lists sandboxed JavaScript, and custom API keys stored per project reach Python and JavaScript steps through a secrets template variable, redacted whenever they are printed.

The API step calls any REST endpoint, which is how a Tool reaches a service with no dedicated integration. You set custom headers and parameters, a JSON body is serialized for you, and the response comes back as a string, JSON, arrayBuffer or blob. There is also an option to throw an error on 4xx or 5xx responses. Switch it on. The Tool then stops at the failed call instead of passing an error body to the next step, and the agent's failure policy can retry, end the task or escalate it to a human.

## Branches, loops and how long a run may last

A step can split into at most four branches. Each branch is judged on its own by rules, a code expression, an AI prompt that answers true or false, or a fallback, so more than one branch can run. Nodes in one branch cannot read nodes in another, so any value two branches share must be produced before the split. Loops process a list in parallel or one item at a time. By default an item that errors is skipped and shown in the Errors tab; you can set the loop to throw a Tool error instead. Run time is capped by type [2].

| What runs | Maximum run time |
|---|---|
| Standard Tool | 15 minutes |
| 24-hour Tool type | 24 hours |
| Agent, after each user action | 15 minutes |
| Bulk run | 24 hours |

A long crawl or a large batch belongs in the 24-hour Tool type rather than a standard Tool racing its 15-minute ceiling. An agent also works within 15 minutes after each user action, so a Tool it calls mid-conversation should finish well inside that window. Heavy loops are the usual cause. Split long lists upstream, cap the pages an extraction step crawls, or move the job onto a schedule where nobody is waiting for a reply.


> 💡 **Choose skip or throw per loop:** Let loops skip errored items for enrichment lists; set them to throw a Tool error where a half-finished batch, such as CRM writes, is worse than a stopped one.


## Webhooks, schedules and the API: starting work without a person

A webhook trigger lets any system that can send an HTTP request start an agent, with a message template, optional Thread ID mapping and optional Unique ID mapping [3]. Map the Unique ID. With it, a repeated event carrying the same ID is ignored, so a sender that retries does not create a duplicate task. Zapier can also start agents as an external trigger, and its Message Workforce event starts a whole Workforce. Our [Workforce guide](/articles/relevance-ai-workforce) covers Tools as shared nodes between agents.

A Tool can itself be the trigger. If it returns an array, it can run on a schedule, combine records from sources such as Salesforce and Airtable, and pass them to an agent, with optional deduping on a field you choose. The catch is fixed inputs: only default values are supported, so the Tool cannot take different inputs from one run to the next. Schedules offer Daily, Weekly, Monthly and Custom dates, or cron in the six-field AWS EventBridge format, which adds a year field to Unix cron.

For your own code, the API is officially supported only for triggering Agents and Tools. The trigger returns no direct response, so the result must go to a configured destination such as Google Sheets, a webhook or another integration. Rate limits depend on the plan, and no numbers are published. The documented SDK is JavaScript/TypeScript, `@relevanceai/sdk`. Keys, regional endpoints and the MCP server are covered in our [API guide](/articles/relevance-ai-api), and app-by-app triggers in the [integrations guide](/articles/relevance-ai-integrations).

## Versions, sharing and who pays for a shared run

Every save of a Tool creates a snapshot you can restore, and edits stay in draft until published. When several agents use one Tool, the editor warns that a change affects all of them, so clone it when one agent needs a variant. Deleting a Tool is permanent: agents lose access, bulk runs in progress may fail and shared links stop working. Sharing takes three forms, a link, an iframe embed or a cloneable template, and any of them makes the Tool public [4].

Who pays differs by form. Runs through a link or embed are charged to the owner's account, so a Tool embedded as a form on your website runs on your credits, whoever fills it in. A cloneable template works the other way: others copy the Tool and run it on their own project and credits, and their copies never receive your later changes. Since May 2026, admins can disable public cloning and embedding per project, which is worth doing before anyone shares a link outside the team.


## FAQ

**Can I use Tools on the Pro plan?**

Yes. Tools, Agents, Workforces and integrations are unlimited on Pro, Team and Enterprise; what differs is the allowance, 2,500 Actions a month on Pro and 7,000 a month on Team.

**Can a Tool run over a whole spreadsheet?**

Relevance AI supports bulk runs, which may last up to 24 hours, and since September 2026 bulk-run CSV uploads handle up to 10,000 rows. Scheduling bulk runs ahead of time requires the Team plan or above.

**Is there a Python SDK for triggering Tools?**

No. Relevance AI's current docs describe a JavaScript/TypeScript SDK, @relevanceai/sdk. Python is available inside a Tool as a code step, not as a client library.


## Tool or agent: deciding where a job belongs

Build a Tool when the job has a fixed shape: the same inputs, the same steps and an output you can check. Hand that Tool to an agent when the order of work depends on judgment, since agents decide for themselves and may not follow the exact path you expect. Keep the meter in mind throughout. One run is one Action, success or failure, so group steps that always run together, map Unique IDs on webhooks, and test errors on purpose before a schedule starts firing at volume.



## Sources

[1] Relevance AI documentation: Plans and credits — https://relevanceai.com/docs/admin/subscriptions/plans (2026-11)
[2] Relevance AI documentation: System quotas — https://relevanceai.com/docs/admin/system-limits (2026-11)
[3] Relevance AI documentation: Webhook Triggers — https://relevanceai.com/docs/build/agents/build-your-agent/agent-triggers/custom-webhook (2026-11)
[4] Relevance AI documentation: Share your Tool — https://relevanceai.com/docs/build/tools/share-your-tool (2026-11)
[5] Relevance AI documentation: Pricing (plans, Actions, Vendor Credits) — https://relevanceai.com/docs/get-started/pricing
[6] Relevance AI Terms and Conditions — https://relevanceai.com/terms-and-conditions
[7] Relevance AI documentation: Changelog — https://relevanceai.com/docs/changelog



## Products mentioned

[p1] Confluence — https://api.colosus.site/m/confluence