# Creating and Configuring
Source: https://docs.fetchhive.com/agents/creating-and-configuring
Create an agent, tune its settings, and add tools in the Fetch Hive editor
Create an agent from the **Agents** page, then tune its behavior in the editor.
## Overview
The **Agents** page shows your active agents and lets you start a new one with **Add Agent**. After you save, Fetch Hive opens the editor automatically. From there, you can adjust **Agent Settings**, add tools, test with **Chat**, and watch save state changes like **Editing...**, **Saving...**, and **Saved**.
## How do I create a new agent?
1. Open **Agents** from the sidebar.
2. Click **Add Agent**.
3) Enter a **Name** for the agent.
4) Choose a **Category** if your workspace uses categories.
5) Click **Save**.
Fetch Hive opens the agent editor as soon as the agent is created.
## How do I configure an agent in the editor?
1. In the editor, select the root agent node to open **Agent Settings**.
2) Update the fields you need, including **Name**, **Description**, **Model**, **Max Tokens**, **Temperature**, **Tool Choice**, **Max Tool Calls**, **Instruction Prompt**, and **Charge Type**.
3) Watch the save indicator in the header while your changes are written. Fetch Hive shows **Editing...** while you have unsaved changes, **Saving...** while it writes them, and **Saved** when the update completes.
Agents can use supported OpenAI, Anthropic, Google Gemini, and xAI models. Some settings change based on the selected model. For example, some models show **Reasoning Effort** or **Max Thinking Tokens** instead of **Temperature**. Gemini 2.5 thinking models and older Claude thinking models show **Max Thinking Tokens**. Gemini 3 Flash models show **Thinking Level** (`minimal`, `low`, `medium`, `high`). Newer adaptive Claude models, including Claude Sonnet 4.6+, Claude Opus 4.6+, Claude Opus 5, and Claude Fable 5, show **Reasoning Effort**. Claude agents also show **Prompt Cache**, with **Disabled**, **5 minutes**, and **1 hour** options for Anthropic prompt caching across repeated agent calls. **Max Tool Calls** appears for OpenAI and xAI agents only (`0` is unlimited): OpenAI sends it as provider `max_tool_calls`, and xAI sends it as `max_turns`. Anthropic, Gemini, and Perplexity agents hide the control.
If a saved agent uses a retired model, Fetch Hive shows a warning in **Agent Settings** and blocks chat/API runs with `model_deprecated`. Select an active model before testing or invoking the agent.
## How do I add an MCP tool?
1. Click the add-tool button in the editor header.
2. In the picker, use search if you need to filter the list.
3. Choose a tool from **MCP Tools**.
Fetch Hive currently shows these active MCP tools in the picker:
* **Auto Summarize**
* **SERP API**
* **Google Search**
* **Google Grounding**
* **Vector Search**
* **GPT Search**
* **xAI Web Search**
* **X Search**
* **Image Generation**
* **Airtable**
* **Linear**
* **Google Calendar**
Tools marked **Soon** are not available yet. If you add a tool, select its node to open the settings sheet for that tool. Some tools expose extra configuration, such as **Dataset** for **Vector Search**, **Context Size** and **Location Country** for **GPT Search**, **Allowed/Excluded Handles**, **Date Range**, and media understanding toggles for **X Search**, or an **Authentication** account for **Airtable** and **Linear**. **xAI Web Search** and **X Search** require an xAI Grok model. **Google Grounding** requires a Gemini model.
## How do I add a workflow tool?
Choose a deployed workflow from **Workflow Tools** in the tool picker. Fetch Hive lets the agent call the selected workflow endpoint variant as a tool. The workflow run keeps its own workflow request ID and logs, and the parent agent trace records the call under `agent.tool.workflow`.
See [Workflow Tools](./workflow-tools) for setup details and logging behavior.
## How do I remove a tool or archive an agent?
To remove an MCP tool, hover over its node in the editor and click the remove action. Fetch Hive asks you to confirm with **Remove tool?** and **Remove tool**.
To archive an agent, open the menu next to the agent name in the editor and choose **Archive**. Fetch Hive asks you to confirm with **Archive agent?** and **Archive agent**.
Archiving removes the agent from the active **Agents** list. For workflow tools, see [Workflow Tools](./workflow-tools). For sub agents, see [Sub Agents](./sub-agents). For testing, see [Testing with Chat](./testing-with-chat).
# Logs
Source: https://docs.fetchhive.com/agents/logs
Review agent runs, filter activity, inspect traces, and debug tool usage in Fetch Hive
Use agent logs to inspect what happened after an agent run starts. In Fetch Hive, this is the main place to review run status, model usage, tool activity, cost, and trace timing outside the editor.
## Overview
Agent logs live under **Logs** in the agents section. The page centers on a table of runs. When you click a row, Fetch Hive opens a run detail sheet with summary metrics and trace data.
This page covers logged runs, not the temporary test conversation in **Chat**. Use **Chat** in the editor to iterate on behavior, then use **Logs** to inspect runs after the fact.
## How do I open agent logs?
1. Open **Agents** in the sidebar.
2. Click **Logs** in the agents section menu.
Fetch Hive opens the agent logs table. On this page, the agents sidebar does not show the **Categories** group, and it does not add the **Source** filter pattern used in prompt and workflow logs.
## What's tracked in the agent logs table?
The main logs table shows summary fields for each run, including:
* **Completed At**
* **Name**
* **Model**
* **Tools**
* **Status**
* **Total Tokens**
* **Total Cost**
* **Duration**
* **API Key**
* **Collaborator**
The **Tools** column shows the tool sources involved in the run. Depending on the run, this can include **Google Search**, **GPT Search**, **xAI Web Search**, **X Search**, **Vector Search**, **SERP**, or **Image Generation**.
**Total Tokens** includes the parent agent response, sub-agent runs, and token-reporting image generation tool calls. In the run detail sheet, hover the token info icon to see the breakdown by parent agent, image generation, and sub-agents.
## How do I filter agent logs?
Use the date range control in the header to pick a custom range or an available preset. Presets include ranges such as **Last 1 Day**, **Last 7 Days**, **Last 30 Days**, and **Last 90 Days**, but longer ranges may require a plan with more log history.
Use **Provider**, **Model**, and **API keys** to narrow the table to the runs you care about.
Use **User metadata** to filter by a tracked metadata property. Choose a property key to find runs where that key exists, or add an exact value to match scalar values such as `cus_123`, `enterprise`, `true`, or `12`.
Click **Clear filters** when you want to reset the active filter state.
Use **Columns** when you want to hide or restore table columns.
## How do I inspect an agent run?
1. Click a row in the logs table.
2. Review the run detail sheet that opens on the right.
The sheet header shows the request ID when it is available, or the run ID as a fallback. It also shows the run status, agent name, and started time.
The summary strip below the header shows the run's **Provider / Model**, **Agent**, **Duration**, **Tokens**, **Credits**, **Cost**, **Tool Calls**, **Owner**, and **Charge Type**.
If the agent still exists and is not archived, the agent name in the summary strip links back to the editor.
## Traces
Use the trace waterfall on the left side of the run detail sheet to understand how the run progressed over time.
When you select a span, the right side updates to show the details for that part of the run. Depending on the span, this can include:
* model response data
* request details
* user metadata
* metadata
* tool input
* tool response
* token and cost details
When the selected span is linked to a tool completion, Fetch Hive shows the tool-specific panels for **Response** and **Input**. When it is linked to the main model completion, Fetch Hive shows the response and request sections for that completion instead.
For sub-agent spans, Fetch Hive also shows the selected child agent run's token and cost contribution. Nested sub-agents are included recursively in the run totals and remain visible in the trace waterfall. If a sub-agent fails, the span is kept with its input, safe failure response, `child_request_id`, metadata diagnostics, and any partial child trace/cost data that was written before failure. Late child runs are reconciled back into the parent trace by `child_request_id` after completion.
For Claude agent completions, the request section can include **Prompt Cache**, which is the configured Anthropic prompt-cache TTL assigned to the run. Actual cache hit and write accounting remains in the cached-token usage fields.
This is the main debugging view for agent runs. Start here when you need to understand whether the agent responded directly, reasoned first, called a tool, or slowed down on a specific step.
## Notes
* Agent logs do not include the **Source** filter pattern used in prompt and workflow logs.
* Agent stream client disconnects are treated as silent cancellations, so they do not appear as failed runs or billing events unless the provider had already completed and usage was committed.
* Fetch Hive tracks user metadata property names over time from agent invokes so the metadata filter can suggest keys your workspace has actually sent. See [Invoke metadata](../user-tracking/invoke-metadata) for request examples.
* This page does not expose a separate analytics or export view for agents.
* Use [Run with API](./run-with-api) when you want to invoke an agent from your own app, and use [Testing with Chat](./testing-with-chat) when you want to iterate inside the editor.
# Auto Summarize
Source: https://docs.fetchhive.com/agents/mcp-tools/auto-summarize
Automatically compress long conversation histories so agents never run out of context window
Auto Summarize keeps long agent conversations working by compressing prior history when it approaches the model's context limit.
## What it does
Every agent has this tool enabled by default. Before each turn, Fetch Hive checks whether the accumulated conversation history is approaching the model's context window. If it is, the prior turns are automatically summarised into a single compact message, and the agent continues with that summary as its starting context instead of the raw history.
The agent retains full awareness of what was discussed — it just works from a condensed version of the earlier turns rather than every token verbatim.
## How it fires
Auto Summarize is not a tool the agent calls. It runs as a server-side check before the model ever sees the conversation. The agent and the LLM are unaware of it — from the model's perspective, it simply receives a well-formed conversation history that fits its context window.
When summarization fires during a streaming run, a `summary` event arrives at the start of the stream before any response tokens:
```json theme={null}
{
"type": "summary",
"summary_text": "The conversation covered AI infrastructure trends. The user asked about evals...",
"original_token_count": 15234,
"context_limit": 200000,
"model": "gpt-4.1",
"provider": "openai"
}
```
In the **Chat** panel inside the agent editor, a **Chat summarized** accordion appears in the conversation at the point where summarization occurred. Click it to expand and read the full summary text and token counts.
See [Run with API](../run-with-api) for how to handle this event in your own integration.
## Enabling and disabling
The tool node appears on every agent canvas with a **System** badge. To disable it for a specific agent:
1. Select the **Auto Summarize** node in the editor.
2. In the settings sheet, switch the toggle to **Disabled**.
Disabling it means the agent will send the full raw history on every turn. If the conversation grows beyond the model's context limit, the oldest messages will be truncated by the model provider.
## Configuration
There are no per-agent configuration options for this tool. The summarization threshold and the model used to write summaries are set at the platform level by your workspace operator.
## Use cases
* Long support or research conversations that span many turns without losing earlier context.
* Agents running in `thread_id` mode where conversations persist across multiple sessions.
* Any use case where you want the agent to stay coherent over a long interaction without manual history management.
## Notes
* Auto Summarize only fires on persistent threads (calls that include a `thread_id`). Single-shot calls and stateless history passed via the `messages` field are not affected.
* The summarization call is made by Fetch Hive — it does not count against your token usage for that turn.
* If the summarization service is unavailable for any reason, the agent run proceeds normally with the full history. The feature is fail-open.
* To test it, use **Chat** in the agent editor — the **Chat summarized** accordion appears when the threshold is crossed.
# Google Grounding
Source: https://docs.fetchhive.com/agents/mcp-tools/google-grounding
Ground Gemini agent responses with Gemini's native Google Search grounding
Google Grounding lets a Gemini agent ground its answer with public web results from Google Search.
## What it does
This tool uses Gemini's native Google Search grounding. Gemini decides when search grounding is useful, runs the search internally, and returns grounding metadata such as search queries, sources, citations, and Search Suggestions.
Use Google Grounding when the agent uses a Gemini model and the answer should be tied to current public web sources.
## Adding the tool to an agent
1. Open a Gemini agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **Google Grounding**.
## Configuration
Fetch Hive does not show extra configuration fields for Google Grounding in this version.
## Google Grounding vs Google Search
* **Google Grounding** is Gemini-native. It is sent to Gemini as a built-in grounding tool and can return citations and Google Search Suggestions.
* **Google Search** is Fetch Hive's SERP-style web search tool. It is powered through the external search tool path and can be used by non-Gemini agents.
## Billing notes
* Hosted Gemini agents use the hosted LLM wallet when Google returns a grounded result.
* Personal/BYOK Gemini agents are not supported yet, so Google Grounding is hosted-only for now.
## Notes
* Google Grounding does not add an MCP server to the provider request.
* Google Grounding remains available on Gemini 2.0, Gemini 2.5, and Gemini 3 Flash. Remote MCP is available on Gemini 2.5 and Gemini 3 Flash and does not change how Grounding runs or is billed.
* Use **Chat** in the editor to see when an agent uses Google Grounding during a test run. See [Testing with Chat](../testing-with-chat).
# Google Search
Source: https://docs.fetchhive.com/agents/mcp-tools/google-search
Add Google Search to an agent so it can search the public web from the Fetch Hive editor
Google Search gives your agent access to live public web search in Fetch Hive.
This is different from [Google Grounding](./google-grounding), which is Gemini's native Google Search grounding tool for Gemini agents.
## What it does
This tool lets an agent look up current information on the web while it responds. Use it when the answer depends on fresh sources instead of static instructions or stored documents.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **Google Search**.
After you add the tool, select its node if you want to review the settings sheet.
## Configuration
Fetch Hive does not currently show extra configuration fields for this tool in the settings sheet.
## Use cases
* Look up current events or recent changes.
* Check public web sources before the agent answers.
* Enrich responses with fresh search results.
## Notes
* On Gemini, this tool requires Gemini 2.5 or Gemini 3 Flash. Use [Google Grounding](./google-grounding) for Gemini-native search, including on Gemini 2.0.
* Use **Chat** in the editor to see when the agent calls **Google Search** during a test run. See [Testing with Chat](../testing-with-chat).
* To add or remove tools from an agent, see [Creating and Configuring](../creating-and-configuring).
# Overview
Source: https://docs.fetchhive.com/agents/mcp-tools/overview
Review the tools available to Fetch Hive agents
Agent tools give your Fetch Hive agent access to built-in capabilities — web and knowledge base search, image generation, connected integrations such as Airtable, Linear, and Google Calendar, and conversation summarization — directly from the agent editor. Most tools use MCP; some, such as native provider search and image generation, run through provider-native or Fetch Hive server-side function calls.
## Model compatibility
The agent editor only shows tools that can run with the agent's current model. If a saved tool becomes incompatible after switching models, it stays on the canvas and is marked **Tool not supported**.
* GPT/OpenAI models support GPT Search, OpenAI Code Interpreter, SERP API, and Google Search.
* Grok/xAI models support xAI Web Search, X Search, SERP API, and Google Search.
* Claude/Anthropic models support Anthropic Web Search, SERP API, and Google Search.
* Perplexity/Sonar models support Sonar Web Search, Perplexity Search, SERP API, and Google Search. Perplexity Search is also available with every other supported model provider.
* Gemini 2.5 and Gemini 3 Flash models support Google Grounding for native search and remote MCP tools such as SERP API, Google Search, Vector Search, File Tools, connected integrations, and custom workspace MCP servers. Gemini 2.0 supports Google Grounding but not remote MCP.
Local or server-side function tools are not remote MCP tools. Image Generation, Auto Summarize, sub-agents, and workflow tools can remain available across supported providers, including Gemini. File read/write uses remote MCP and therefore requires Gemini 2.5 or Gemini 3 Flash.
## What you'll find here
* [Auto Summarize](./auto-summarize) - Automatically compress long conversation histories so agents never run out of context window
* [SERP API](./serp-api) - Pull SERP results and SEO-oriented search data into an agent
* [Google Search](./google-search) - Let an agent search the public web for fresh information
* [Google Grounding](./google-grounding) - Ground Gemini responses with Gemini's native Google Search grounding
* [Vector Search](./vector-search) - Search your Knowledge Base from your agent
* [GPT Search](./gpt-search) - Run GPT-powered web search with context and location controls
* [OpenAI Code Interpreter](./openai-code-interpreter) - Run Python in an OpenAI sandbox for exact computation and data analysis
* [xAI Web Search](./xai-search) - Let a Grok-powered agent search the public web using xAI's native web search
* [X Search](./x-search) - Search X/Twitter posts and content using Grok's native X search
* [Anthropic Web Search](./anthropic-web-search) - Let a Claude-powered agent search the public web using Anthropic's native web search
* [Perplexity Search](./perplexity-search-api) - Use the standalone Search API from any supported model provider
* [Sonar Web Search](./perplexity-search) - Use native web search with Perplexity Sonar models
* [Image Generation](./image-generation) - Let an agent generate images on demand using OpenAI's image API
* [Airtable](./airtable) - Let an agent create, list, update, and retrieve records in your connected Airtable base
* [Linear](./linear) - Let an agent create issues, search and update tickets, and list teams in your connected Linear workspace
* [Google Calendar](./googlecalendar) - Let an agent create, list, find, and manage events in your connected Google Calendar account
* [Google Analytics](./google_analytics) - Let an agent query GA4 reports and property metadata from your connected Google Analytics account
* [Google Ads](./googleads) - Let an agent query campaigns, run GAQL reports, and manage audiences from your connected Google Ads account
* [Google Maps](./google-maps) - Let an agent geocode addresses, search places, and calculate routes from your connected Google Maps account
* [Calendly](./calendly) - Let an agent view upcoming meetings, check availability, and manage bookings in your connected Calendly account
* [Cal.com](./cal) - Let an agent view upcoming meetings, check availability, and manage bookings in your connected Cal.com account
* [Google Drive](./googledrive) - Let an agent upload, download, search, and manage files in your connected Google Drive account
* [Google Sheets](./google-sheets) - Let an agent create, search, read, and update spreadsheets in your connected Google Sheets account
* [Google Docs](./google-docs) - Let an agent create, search, copy, and update documents in your connected Google Docs account
* [Gmail](./gmail) - Let an agent send, read, and search email in your connected Gmail account
* [Slack](./slack) - Let an agent send, read, and search Slack messages in your connected workspace
* [HubSpot](./hubspot) - Let an agent manage contacts, companies, deals, and CRM activity in your connected HubSpot account
* [Klaviyo](./klaviyo) - Let an agent manage profiles, lists, campaigns, and events in your connected Klaviyo account
* [Pipedrive](./pipedrive) - Let an agent manage persons, organizations, deals, leads, and pipeline activity in your connected Pipedrive account
* [LinkedIn](./linkedin) - Let an agent publish posts and research LinkedIn profiles from your connected account
* [Supabase](./supabase) - Let an agent query tables, run SQL, and manage Supabase projects from your connected account
To add one of these tools to an agent, see [Creating and Configuring](../creating-and-configuring).
# SERP API
Source: https://docs.fetchhive.com/agents/mcp-tools/serp-api
Add SERP API to an agent so it can work with search results and SEO-oriented search data
SERP API gives your agent access to search results and SEO-oriented search data from the Fetch Hive editor.
## What it does
This tool adds search-result and SEO-oriented lookup capability to an agent. Use it when the agent needs to work with SERP data instead of answering from its own model context alone.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **SERP API**.
After you add the tool, Fetch Hive shows it as an **MCP** node in the editor.
## Configuration
Fetch Hive does not currently show extra configuration fields for this tool in the settings sheet.
## Use cases
* Check search rankings for a query.
* Compare SERP results across topics or prompts.
* Support SEO research tasks inside an agent workflow.
## Notes
* To test how the tool behaves in a conversation, see [Testing with Chat](../testing-with-chat).
* To add or remove tools from an agent, see [Creating and Configuring](../creating-and-configuring).
# Vector Search
Source: https://docs.fetchhive.com/agents/mcp-tools/vector-search
Add Vector Search to an agent so it can search your workspace Knowledge Base
Vector Search lets your agent search your workspace Knowledge Base from the Fetch Hive editor.
## What it does
This tool connects an agent to the Knowledge Base in your workspace. Use it when you want the agent to retrieve information from your Knowledge Base before it answers.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **Vector Search**.
4. Select the Knowledge Base this tool should search, then add the tool.
The tool is created only after a Knowledge Base is selected. If no active Knowledge Base exists yet, create one first.
## Configuration
Vector Search uses the **Knowledge Base** field in the settings sheet to choose which Knowledge Base content the agent searches.
| Option | Description |
| ------------------ | ------------------------------------------------------------------------------ |
| **Knowledge Base** | Chooses which Knowledge Base content the agent searches when it uses this tool |
1. Select the **Vector Search** node in the editor.
2. In the settings sheet, open **Knowledge Base**.
3. Choose the Knowledge Base content you want this agent to search.
The selected item appears on the tool node summary in the canvas. Existing Vector Search tools without a Knowledge Base stay disabled until you select one.
If a Vector Search tool somehow has no active Knowledge Base at run time, the agent run stops with a configuration error instead of silently continuing without search.
## Use cases
* Answer questions from internal documents or product docs.
* Build support or ops agents that search a curated Knowledge Base.
* Retrieve source material before the agent writes a response.
## Notes
* Vector Search depends on content in your Knowledge Base. See [Knowledge Bases](../../knowledge-base/overview) and [Creating & Editing](../../knowledge-base/creating-and-editing).
* To test how retrieval changes an answer, use [Testing with Chat](../testing-with-chat).
* To add or remove tools from an agent, see [Creating and Configuring](../creating-and-configuring).
# Overview
Source: https://docs.fetchhive.com/agents/overview
Build, test, and run chat Agents in Fetch Hive
Agents in Fetch Hive combine model settings, instructions, MCP tools, workflow tools, and sub-agents into one assistant you can test in the app and invoke from code.
Agents are different from [Hive Agents](../hive-agents/overview). A chat Agent handles a request or conversation directly. A Hive Agent is a dashboard-only durable task loop with **PLAN**, **EXECUTE**, **VERIFY**, and **REPEAT** stages.
## What you'll find here
* [Creating and Configuring](./creating-and-configuring) - Create an agent, open the editor, and manage its settings and tools
* [Testing with Chat](./testing-with-chat) - Test messages in the editor before you run an agent from your own code
* [Workflow Tools](./workflow-tools) - Let an agent run a deployed workflow as a tool
* [Sub Agents](./sub-agents) - Let one agent call another agent in the same workspace as a tool
* [Run with API](./run-with-api) - Invoke an agent over HTTP
* [Run with Python SDK](./run-with-python-sdk) - Invoke an agent from Python with `fetch-hive-sdk`
* [Run with Node.js SDK](./run-with-nodejs-sdk) - Invoke an agent from Node.js with `@fetch-hive/sdk`
* [Run with Ruby SDK](./run-with-ruby-sdk) - Invoke an agent from Ruby with the `fetch_hive` gem
* [Run with PHP SDK](./run-with-php-sdk) - Invoke an agent from PHP with `fetch-hive/sdk`
* [Logs](./logs) - Inspect agent runs and debug production behavior
* [MCP Tools](./mcp-tools/overview) - Learn what each built-in MCP tool adds to an agent
# Run with API
Source: https://docs.fetchhive.com/agents/run-with-api
Invoke an agent with the public API using your workspace API key, an agent ID, and a message
Use the public agent invoke endpoint when you want to send a message to an agent from your own app or service. In Fetch Hive, you can copy the request shape from **More** -> **Get Code** in the agents sidebar or from **Get Code** in the agent editor control bar.
## Authentication
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
See [API Keys](../workspace/api-keys) for how to create and manage keys.
## Endpoint
`POST https://api.fetchhive.com/v1/agent/invoke`
If you want Fetch Hive to generate the cURL example for you, open **Agents**, then use **More** -> **Get Code**. If you are already in the editor for a specific agent, click **Get Code** in the editor control bar instead.
## Request
Use this request shape:
| Field | Type | Required | Description |
| ------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent` | string | Yes | The agent ID |
| `message` | string | Yes | The message you want to send to the agent |
| `streaming` | boolean | No | Whether the response should stream back as events |
| `thread_id` | string | No | An arbitrary string identifying the conversation thread. Fetch Hive creates a new thread on first use and resumes it on subsequent calls with the same value. |
| `messages` | array | No | Previous conversation turns supplied by the caller. Used as context without persisting to the database. Each item: `{ "content": string, "role": "user" \| "assistant" \| "system", "attachments"?: array }`. |
| `attachments` | array | No | HTTPS file URLs attached to the current `message`. Each item can be a URL string or an object with `file_url`. Supported document files are CSV, XLSX, PDF, DOCX, and text/Markdown by extension. Images can also be passed here. |
| `metadata` | object | No | Flat caller-defined metadata for audit and log filtering. This is not added to the agent prompt. |
`metadata` must be flat and scalar-only: strings, numbers, booleans, or `null`. Nested objects and arrays return a validation error before the run starts.
`attachments` items can be simple URL strings:
```json theme={null}
[
"https://example.com/customer-brief.pdf",
"https://example.com/customer-brief.pdf"
]
```
They can also use this object shape when you want to provide metadata:
```json theme={null}
{
"file_url": "https://example.com/customer-brief.pdf",
"file_name": "customer-brief.pdf",
"file_type": "application/pdf"
}
```
Only `https://` URLs are accepted. Up to five attachments are allowed per
message. Document attachments are
exposed to the agent through the system `read_file` tool as an
`` manifest; the agent calls `read_file` before relying on
document contents. If an attachment URL or type is invalid, Fetch Hive returns
a `422` validation error instead of opening the stream. The error uses the
standard `error_code`, `error`, and `message` fields; `error` and `message` are
localized from the authenticated account language when available.
Supported document attachments:
* CSV: `text/csv`, `.csv`
* XLSX: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `.xlsx`
* PDF: `application/pdf`, `.pdf`
* DOCX: `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `.docx`
* Text and Markdown by extension: `.txt`, `.md`, `.markdown`
For extensionless URLs, such as Fetch Hive Media Library URLs, pass the URL
directly. Fetch Hive allow-lists the URL for `read_file`, and the file tool
detects the actual type when it fetches the file.
The in-app snippet shows the same body shape:
```json theme={null}
{
"agent": "AGENT_UUID",
"message": "Your message here",
"streaming": true,
"metadata": {
"customer_id": "cus_123",
"plan": "enterprise"
}
}
```
## Basic example
```bash theme={null}
curl 'https://api.fetchhive.com/v1/agent/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
"agent": "AGENT_UUID",
"message": "Summarize the latest AI infrastructure trends",
"metadata": {
"customer_id": "cus_123",
"plan": "enterprise"
},
"attachments": [
"https://example.com/customer-brief.pdf"
],
"streaming": true
}' \
--compressed
```
This matches the cURL snippet shown in the product. The invoke dialog currently shows **cURL**, while **Python** and **TypeScript** still show **Coming Soon**.
Use `metadata` for audit fields you want to see or filter in logs, such as customer IDs, plan names, regions, or experiment names. It is stored with the run and displayed under **User metadata** in logs. See [Invoke metadata](../user-tracking/invoke-metadata) for examples and log filtering details.
## Response
If `streaming` is `true`, the route returns a stream of events rather than one final JSON object. If the provider fails after the stream has opened, the route sends a final `error` event before closing the stream. If the client disconnects first, Fetch Hive treats it as a silent cancellation and does not create a failed agent run, bill usage, or report a provider-error event unless the provider had already completed and usage was committed.
### Streaming response
The stream can include a summary event, reasoning chunks, response chunks, tool events, a final usage event, or an error event. Events arrive in this order when all successful events are present: `summary` → `reasoning` → `response` → `tool` → `usage`. An `error` event can arrive instead of `usage` if the provider fails mid-stream.
Summary event (only emitted on threads with auto-summarization enabled):
```json theme={null}
{
"type": "summary",
"summary_text": "The conversation covered AI infrastructure trends. The user asked about evals and tool routing...",
"original_token_count": 15234,
"context_limit": 200000,
"model": "gpt-4.1",
"provider": "openai"
}
```
This event fires at the start of the stream when the accumulated thread history has crossed the auto-summarization threshold. It means the prior conversation was compressed into a summary before being sent to the model — the agent retains the context, but the raw history has been condensed. `original_token_count` is the token count before compression; `context_limit` is the model's total context window. You can surface this to users as a "conversation summarized" indicator, or ignore it — your app's behaviour is unaffected either way.
Reasoning event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "reasoning",
"response": "Looking at the latest model releases..."
}
```
Response event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "response",
"response": "Teams are standardizing around evals, routing, and observability.",
"done": false
}
```
Tool event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "tool",
"tool_id": "tool_123",
"tool": "google_search",
"tool_input": {
"query": "latest AI infrastructure trends 2026"
},
"observation": {
"results": []
}
}
```
Final usage event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "usage",
"usage": {
"duration": 4.79230260848999,
"input_tokens": {
"total_tokens": 24,
"cached_tokens": 0,
"cached_read_tokens": 0,
"cache_write_tokens": 0
},
"output_tokens": {
"total_tokens": 170,
"reasoning_tokens": 64
},
"total_tokens": 194
},
"stop_reason": "completed"
}
```
Error event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "error",
"id": "msg_019d52846ea37682b03522fd0695cc43",
"error": "openai provider stream error: HTTP 400: invalid request",
"message": "openai provider stream error: HTTP 400: invalid request",
"provider": "openai",
"error_type": "provider_stream_error",
"status_code": 502
}
```
### Non-streaming response
If `streaming` is `false`, the route returns one JSON response with the generated output, usage data, and the request ID you can use to inspect the run in **Logs**. Provider execution failures return `502 Bad Gateway` with an `error` message.
The exact output field can vary by provider, but the response includes the run metadata you need. For example:
```json theme={null}
{
"request_id": "req_019d528660dd7e22b15e5b13a1931c50",
"model": "gpt-5-nano-2025-08-07",
"duration": 4.641960144042969,
"response": "Teams are moving from simple wrappers to systems with evals, tool routing, and tighter cost controls.",
"reasoning": "The request asks for a short summary of current infrastructure trends.",
"usage": {
"input_tokens": {
"total_tokens": 24,
"cached_tokens": 0,
"cached_read_tokens": 0,
"cache_write_tokens": 0
},
"output_tokens": {
"total_tokens": 187,
"reasoning_tokens": 64
},
"total_tokens": 211
},
"stop_reason": "completed"
}
```
If the agent uses tools, the non-streaming response can also include tool execution details.
## Multi-turn conversations
The invoke endpoint supports two approaches for multi-turn conversations.
### Persistent threads (Fetch Hive manages history)
Pass a `thread_id` — any string you choose — and Fetch Hive will automatically create the thread on the first call and resume it on every subsequent call with the same value. Message history is stored in Fetch Hive and included in the context automatically.
```bash theme={null}
# First turn
curl 'https://api.fetchhive.com/v1/agent/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
"agent": "AGENT_UUID",
"message": "What are the main AI infrastructure trends right now?",
"streaming": true,
"thread_id": "user-456-support-session"
}'
# Second turn — same thread_id resumes the conversation
curl 'https://api.fetchhive.com/v1/agent/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
"agent": "AGENT_UUID",
"message": "Which of those trends have the most enterprise adoption?",
"streaming": true,
"thread_id": "user-456-support-session"
}'
```
You can use any string as a `thread_id` — a user ID, session ID, ticket number, or any other identifier that makes sense for your use case.
### Stateless history (caller manages history)
If you prefer to manage conversation state yourself, pass the previous turns in the `messages` array. Fetch Hive uses the provided history for context but does not persist it.
```bash theme={null}
curl 'https://api.fetchhive.com/v1/agent/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
"agent": "AGENT_UUID",
"message": "Which of those trends have the most enterprise adoption?",
"streaming": true,
"messages": [
{
"content": "What are the main AI infrastructure trends right now?",
"role": "user",
"attachments": [
{
"file_url": "https://example.com/market-data.csv",
"file_name": "market-data.csv",
"file_type": "text/csv"
}
]
},
{ "content": "Teams are focusing on evals, tool routing, and observability.", "role": "assistant" }
]
}'
```
For caller-managed sessions, send up to 50 account/workspace-owned Asset UUIDs
in `known_artifact_refs`. Put the UUIDs selected for the current turn in
`artifact_refs`; `attachments` plus `artifact_refs` can contain at most five
items. An `artifact_ref` must also appear in `known_artifact_refs`.
Persistent `thread_id` calls derive known artifacts from the saved chat and
ignore conflicting client discovery metadata. External document and image URLs
continue to use `attachments` or `messages[].attachments`. External audio URLs
are unsupported.
Streaming calls can receive an `artifact` event in addition to existing tool
events. Non-stream responses include an `artifacts` array.
Use `messages` when you already maintain your own chat state and do not need Fetch Hive to store the conversation history.
## Next steps
* [Logs](./logs)
* [Testing with Chat](./testing-with-chat)
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
# Run with Node.js SDK
Source: https://docs.fetchhive.com/agents/run-with-nodejs-sdk
Invoke an agent from Node.js or TypeScript with the @fetch-hive/sdk package
Use the official `@fetch-hive/sdk` package when you want to send a message to an agent from Node.js or TypeScript. The SDK wraps the public [`POST /v1/agent/invoke`](../api-reference/agents/invoke) endpoint, handles authentication, exposes streaming as an `AsyncIterable`, and supports multimodal inputs.
## Installation
```bash theme={null}
npm install @fetch-hive/sdk
# or
yarn add @fetch-hive/sdk
# or
pnpm add @fetch-hive/sdk
```
The SDK targets Node.js 18+ (uses the global `fetch`) and ships with TypeScript types.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key:
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```typescript theme={null}
import { FetchHive } from '@fetch-hive/sdk';
const client = new FetchHive();
```
Or pass the key explicitly:
```typescript theme={null}
const client = new FetchHive({ apiKey: 'fhk_...' });
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Send a message to an agent and read the final response:
```typescript theme={null}
import { FetchHive } from '@fetch-hive/sdk';
const client = new FetchHive();
const reply = await client.invokeAgent({
agent: 'AGENT_UUID',
message: 'Summarize the latest AI infrastructure trends',
});
console.log(reply.response);
```
See the [non-streaming response shape](../api-reference/agents/invoke#response).
## Method reference
| Field | Type | Required | Description |
| ----------- | ----------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `agent` | `string` | Yes | The agent ID |
| `message` | `string` | Yes | The message you want to send |
| `thread_id` | `string` | No | An arbitrary string identifying a persistent conversation thread |
| `messages` | `Array<{ role, content, attachments? }>` | No | Caller-managed conversation history |
| `user` | `string` | No | Opaque caller identifier surfaced in [User Tracking](../user-tracking/overview) |
| `metadata` | `Record` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
The SDK injects `streaming: false` for `invokeAgent`. To stream, use `invokeAgentStream` (below).
## Handling the response
```typescript theme={null}
const reply = await client.invokeAgent({
agent: 'AGENT_UUID',
message: 'Hello',
});
console.log(reply.response); // final text
console.log(reply.model); // model identifier
console.log(reply.usage); // token usage breakdown
console.log(reply.request_id); // use this to look up the run in Logs
console.log(reply.tool_calls); // tool invocations made during the run
```
## Streaming
Use `invokeAgentStream` to receive Server-Sent Events as they arrive. The method returns an `AsyncIterable`:
```typescript theme={null}
for await (const chunk of client.invokeAgentStream({
agent: 'AGENT_UUID',
message: 'Summarize the latest AI infrastructure trends',
thread_id: 'user-456-support-session',
})) {
if (chunk.type === 'response') {
process.stdout.write(chunk.response ?? '');
} else if (chunk.type === 'tool') {
console.log(`\n[Calling tool: ${chunk.tool}]`);
} else if (chunk.type === 'usage') {
console.log('\n\nUsage:', chunk.usage);
}
}
```
The stream yields the same event types documented in [Invoke Agent → Response](../api-reference/agents/invoke#response): `summary` (when auto-summarization fires), `reasoning`, `response`, `tool`, a final `usage` event, or an `error` event if the provider fails mid-stream.
## Multi-turn conversations
### Persistent threads
Pass any string as `thread_id` and Fetch Hive will create the thread on the first call and resume it on subsequent calls with the same value:
```typescript theme={null}
await client.invokeAgent({
agent: 'AGENT_UUID',
message: 'What are the main AI infrastructure trends right now?',
thread_id: 'user-456-support-session',
});
await client.invokeAgent({
agent: 'AGENT_UUID',
message: 'Which of those trends have the most enterprise adoption?',
thread_id: 'user-456-support-session',
});
```
### Stateless history
Manage state yourself by passing the previous turns in `messages`. Fetch Hive uses the supplied history for context but does not persist it:
```typescript theme={null}
await client.invokeAgent({
agent: 'AGENT_UUID',
message: 'Which of those trends have the most enterprise adoption?',
messages: [
{ role: 'user', content: 'What are the main AI infrastructure trends right now?' },
{ role: 'assistant', content: 'Teams are focusing on evals, tool routing, and observability.' },
],
});
```
## Multimodal inputs
Attach images to the current message with `attachments`:
```typescript theme={null}
const result = await client.invokeAgent({
agent: 'vision-agent',
message: 'Describe this image',
attachments: ['https://example.com/photo.jpg'],
});
console.log(result.response);
```
URLs must start with `https://`.
## Configuration
| Option | Default | Description |
| --------- | -------------------------------- | ------------------------------- |
| `apiKey` | `process.env.FETCH_HIVE_API_KEY` | Bearer token from the dashboard |
| `baseURL` | `https://api.fetchhive.com/v1` | Override the API base URL |
```typescript theme={null}
const client = new FetchHive({
apiKey: 'fhk_...',
baseURL: 'https://api.fetchhive.com/v1',
});
```
## Errors
Non-2xx responses throw an `Error` whose message includes the status code and response body:
```typescript theme={null}
try {
const reply = await client.invokeAgent({
agent: 'AGENT_UUID',
message: 'Hello',
});
} catch (err) {
console.error('Fetch Hive error:', err);
}
```
See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for status code meanings.
## Links
* [Package on npm](https://www.npmjs.com/package/@fetch-hive/sdk)
* [Source on GitHub](https://github.com/Fetch-Hive/nodejs-sdk)
## Next steps
* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Invoke Agent](../api-reference/agents/invoke) - Full endpoint reference
# Run with PHP SDK
Source: https://docs.fetchhive.com/agents/run-with-php-sdk
Invoke an agent from PHP with the fetch-hive/sdk Composer package
Use the official `fetch-hive/sdk` Composer package when you want to send a message to an agent from PHP. The SDK wraps the public [`POST /v1/agent/invoke`](../api-reference/agents/invoke) endpoint, handles authentication, exposes streaming responses as a generator, and accepts multimodal inputs.
## Installation
```bash theme={null}
composer require fetch-hive/sdk
```
The SDK requires PHP 8.1+ and uses Guzzle as its HTTP client.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the client reads it automatically):
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```php theme={null}
'fhk_...']);
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Send a message to an agent and read the final response:
```php theme={null}
invokeAgent([
'agent' => 'AGENT_UUID',
'message' => 'Summarize the latest AI infrastructure trends',
]);
echo $reply['response'];
```
See the [non-streaming response shape](../api-reference/agents/invoke#response).
## Method reference
| Key | Type | Required | Description |
| ----------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `agent` | `string` | Yes | The agent ID |
| `message` | `string` | Yes | The message you want to send |
| `thread_id` | `string` | No | An arbitrary string identifying a persistent conversation thread |
| `messages` | `array` | No | Caller-managed conversation history. Each item: `['role' => 'user' \| 'assistant' \| 'system', 'content' => string]`. |
| `user` | `string` | No | Opaque caller identifier surfaced in [User Tracking](../user-tracking/overview) |
| `metadata` | `array` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
The SDK injects `streaming: false` for `invokeAgent`. To stream, use `invokeAgentStream` (below).
## Handling the response
```php theme={null}
$reply = $client->invokeAgent([
'agent' => 'AGENT_UUID',
'message' => 'Hello',
]);
echo $reply['response']; // final text
echo $reply['model']; // model identifier
print_r($reply['usage']); // token usage breakdown
echo $reply['request_id']; // use this to look up the run in Logs
print_r($reply['tool_calls']); // tool invocations made during the run
```
## Streaming
Use `invokeAgentStream` to receive Server-Sent Events as they arrive. The method returns a `Generator`:
```php theme={null}
foreach ($client->invokeAgentStream([
'agent' => 'AGENT_UUID',
'message' => 'Summarize the latest AI infrastructure trends',
'thread_id' => 'user-456-support-session',
]) as $chunk) {
match ($chunk['type']) {
'response' => print($chunk['response'] ?? ''),
'tool' => print("\nCalling tool: " . ($chunk['tool'] ?? '')),
'usage' => print("\n\nUsage: " . json_encode($chunk['usage'])),
default => null,
};
}
```
The stream yields the same event types documented in [Invoke Agent → Response](../api-reference/agents/invoke#response): `summary` (when auto-summarization fires), `reasoning`, `response`, `tool`, a final `usage` event, or an `error` event if the provider fails mid-stream.
## Multi-turn conversations
### Persistent threads
Pass any string as `thread_id` and Fetch Hive will create the thread on the first call and resume it on subsequent calls with the same value:
```php theme={null}
$client->invokeAgent([
'agent' => 'AGENT_UUID',
'message' => 'What are the main AI infrastructure trends right now?',
'thread_id' => 'user-456-support-session',
]);
$client->invokeAgent([
'agent' => 'AGENT_UUID',
'message' => 'Which of those trends have the most enterprise adoption?',
'thread_id' => 'user-456-support-session',
]);
```
### Stateless history
Manage state yourself by passing the previous turns in `messages`. Fetch Hive uses the supplied history for context but does not persist it:
```php theme={null}
$client->invokeAgent([
'agent' => 'AGENT_UUID',
'message' => 'Which of those trends have the most enterprise adoption?',
'messages' => [
['role' => 'user', 'content' => 'What are the main AI infrastructure trends right now?'],
['role' => 'assistant', 'content' => 'Teams are focusing on evals, tool routing, and observability.'],
],
]);
```
## Multimodal inputs
Attach images to the current message with `attachments`:
```php theme={null}
$result = $client->invokeAgent([
'agent' => 'vision-agent',
'message' => 'Describe this image',
'attachments' => ['https://example.com/photo.jpg'],
]);
echo $result['response'];
```
URLs must start with `https://`.
## Configuration
| Option | Default | Description |
| ---------- | ------------------------------ | ------------------------------- |
| `api_key` | `FETCH_HIVE_API_KEY` env var | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL |
| `timeout` | `120` | Request timeout in seconds |
```php theme={null}
$client = new FetchHive([
'api_key' => 'fhk_...',
'base_url' => 'https://api.fetchhive.com/v1',
'timeout' => 120.0,
]);
```
## Errors
Non-2xx responses throw `FetchHive\Sdk\Exception\ApiException` carrying the status code and response body:
```php theme={null}
use FetchHive\Sdk\Exception\ApiException;
try {
$reply = $client->invokeAgent([
'agent' => 'AGENT_UUID',
'message' => 'Hello',
]);
} catch (ApiException $e) {
error_log('Fetch Hive error: ' . $e->getMessage());
}
```
See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for status code meanings.
## Links
* [Package on Packagist](https://packagist.org/packages/fetch-hive/sdk)
* [Source on GitHub](https://github.com/Fetch-Hive/php-sdk)
## Next steps
* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Invoke Agent](../api-reference/agents/invoke) - Full endpoint reference
# Run with Python SDK
Source: https://docs.fetchhive.com/agents/run-with-python-sdk
Invoke an agent from Python with the fetch-hive-sdk package
Use the official `fetch-hive-sdk` package when you want to send a message to an agent from Python. The SDK wraps the public [`POST /v1/agent/invoke`](../api-reference/agents/invoke) endpoint, handles authentication, supports streaming and multimodal inputs, and exposes both synchronous and `asyncio` variants.
## Installation
```bash theme={null}
pip install fetch-hive-sdk
```
The SDK requires Python 3.9+ and uses `httpx` under the hood.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the SDK reads it automatically):
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```python theme={null}
from fetch_hive_sdk import FetchHive
client = FetchHive()
```
Or pass the key explicitly:
```python theme={null}
client = FetchHive(api_key="fhk_...")
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Send a message to an agent and read the final response:
```python theme={null}
from fetch_hive_sdk import FetchHive
client = FetchHive()
reply = client.invoke_agent(
agent="AGENT_UUID",
message="Summarize the latest AI infrastructure trends",
)
print(reply["response"])
```
See the [non-streaming response shape](../api-reference/agents/invoke#response).
## Method reference
| Argument | Type | Required | Description |
| ----------- | ------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agent` | `str` | Yes | The agent ID |
| `message` | `str` | Yes | The message you want to send |
| `thread_id` | `str` | No | An arbitrary string identifying a persistent conversation thread. Fetch Hive creates the thread on first use and resumes it on subsequent calls. |
| `messages` | `list[dict]` | No | Caller-managed conversation history. Each item: `{"role": "user" \| "assistant" \| "system", "content": str}`. |
| `user` | `str` | No | Opaque caller identifier surfaced in [User Tracking](../user-tracking/overview) |
| `metadata` | `dict[str, str \| int \| float \| bool \| None]` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
The SDK injects `streaming: false` for `invoke_agent`. To stream, use `invoke_agent_stream` (below).
## Handling the response
```python theme={null}
reply = client.invoke_agent(agent="AGENT_UUID", message="Hello")
print(reply["response"]) # final text
print(reply["model"]) # model identifier
print(reply["usage"]) # token usage breakdown
print(reply["request_id"]) # use this to look up the run in Logs
print(reply.get("tool_calls")) # tool invocations made during the run
```
## Streaming
Use `invoke_agent_stream` to receive Server-Sent Events as they arrive. The method returns a generator that yields parsed event dicts:
```python theme={null}
for chunk in client.invoke_agent_stream(
agent="AGENT_UUID",
message="Summarize the latest AI infrastructure trends",
thread_id="user-456-support-session",
):
if chunk.get("type") == "response":
print(chunk.get("response", ""), end="", flush=True)
elif chunk.get("type") == "tool":
print(f"\n[Calling tool: {chunk.get('tool')}]")
elif chunk.get("type") == "usage":
print("\n\nUsage:", chunk["usage"])
```
The stream yields the same event types documented in [Invoke Agent → Response](../api-reference/agents/invoke#response): `summary` (when auto-summarization fires), `reasoning`, `response`, `tool`, a final `usage` event, or an `error` event if the provider fails mid-stream.
### Async streaming
For `asyncio` applications, use `ainvoke_agent_stream`. It has the same arguments but returns an async iterator:
```python theme={null}
import asyncio
from fetch_hive_sdk import FetchHive
async def main():
client = FetchHive()
async for chunk in client.ainvoke_agent_stream(
agent="AGENT_UUID",
message="Hello",
thread_id="user-456-support-session",
):
if chunk.get("type") == "response":
print(chunk.get("response", ""), end="", flush=True)
asyncio.run(main())
```
## Multi-turn conversations
### Persistent threads
Pass any string as `thread_id` and Fetch Hive will create the thread on the first call and resume it on subsequent calls with the same value:
```python theme={null}
client.invoke_agent(
agent="AGENT_UUID",
message="What are the main AI infrastructure trends right now?",
thread_id="user-456-support-session",
)
client.invoke_agent(
agent="AGENT_UUID",
message="Which of those trends have the most enterprise adoption?",
thread_id="user-456-support-session",
)
```
### Stateless history
Manage state yourself by passing the previous turns in `messages`. Fetch Hive uses the supplied history for context but does not persist it:
```python theme={null}
client.invoke_agent(
agent="AGENT_UUID",
message="Which of those trends have the most enterprise adoption?",
messages=[
{"role": "user", "content": "What are the main AI infrastructure trends right now?"},
{"role": "assistant", "content": "Teams are focusing on evals, tool routing, and observability."},
],
)
```
## Multimodal inputs
Attach images to the current message with `attachments`:
```python theme={null}
result = client.invoke_agent(
agent="vision-agent",
message="Describe this image",
attachments=["https://example.com/photo.jpg"],
)
print(result["response"])
```
URLs must start with `https://`.
## Configuration
| Option | Default | Description |
| ---------- | ------------------------------ | ------------------------------- |
| `api_key` | `FETCH_HIVE_API_KEY` env var | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL |
| `timeout` | `120` | Request timeout in seconds |
```python theme={null}
client = FetchHive(
api_key="fhk_...",
base_url="https://api.fetchhive.com/v1",
timeout=120,
)
```
## Errors
Non-2xx responses raise an `httpx.HTTPStatusError` with the status code and response body:
```python theme={null}
import httpx
try:
reply = client.invoke_agent(agent="AGENT_UUID", message="Hello")
except httpx.HTTPStatusError as exc:
print("Fetch Hive returned", exc.response.status_code, exc.response.text)
```
See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for status code meanings.
## Links
* [Package on PyPI](https://pypi.org/project/fetch-hive-sdk/)
* [Source on GitHub](https://github.com/Fetch-Hive/python-sdk)
## Next steps
* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Invoke Agent](../api-reference/agents/invoke) - Full endpoint reference
# Run with Ruby SDK
Source: https://docs.fetchhive.com/agents/run-with-ruby-sdk
Invoke an agent from Ruby with the fetch_hive gem
Use the official `fetch_hive` gem when you want to send a message to an agent from Ruby. The SDK wraps the public [`POST /v1/agent/invoke`](../api-reference/agents/invoke) endpoint, handles authentication, supports streaming via a block, and accepts multimodal inputs.
## Installation
Add to your `Gemfile`:
```ruby theme={null}
gem "fetch_hive"
```
Then run:
```bash theme={null}
bundle install
```
Or install directly:
```bash theme={null}
gem install fetch_hive
```
The gem uses `faraday` under the hood and supports Ruby 3.0+.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the client reads it automatically):
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```ruby theme={null}
require "fetch_hive"
client = FetchHive::Client.new
```
Or pass the key explicitly:
```ruby theme={null}
client = FetchHive::Client.new(api_key: "fhk_...")
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Send a message to an agent and read the final response:
```ruby theme={null}
require "fetch_hive"
client = FetchHive::Client.new
reply = client.invoke_agent(
agent: "AGENT_UUID",
message: "Summarize the latest AI infrastructure trends"
)
puts reply["response"]
```
See the [non-streaming response shape](../api-reference/agents/invoke#response).
## Method reference
| Keyword | Type | Required | Description |
| ----------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `agent` | `String` | Yes | The agent ID |
| `message` | `String` | Yes | The message you want to send |
| `thread_id` | `String` | No | An arbitrary string identifying a persistent conversation thread |
| `messages` | `Array` | No | Caller-managed conversation history. Each item: `{ role: "user" \| "assistant" \| "system", content: String }`. |
| `user` | `String` | No | Opaque caller identifier surfaced in [User Tracking](../user-tracking/overview) |
| `metadata` | `Hash` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
The SDK injects `streaming: false` for `invoke_agent`. To stream, use `invoke_agent_stream` (below).
## Handling the response
```ruby theme={null}
reply = client.invoke_agent(agent: "AGENT_UUID", message: "Hello")
puts reply["response"] # final text
puts reply["model"] # model identifier
puts reply["usage"] # token usage breakdown
puts reply["request_id"] # use this to look up the run in Logs
puts reply["tool_calls"] # tool invocations made during the run
```
## Streaming
Use `invoke_agent_stream` to receive Server-Sent Events as they arrive. The method yields each parsed event hash to the block:
```ruby theme={null}
client.invoke_agent_stream(
agent: "AGENT_UUID",
message: "Summarize the latest AI infrastructure trends",
thread_id: "user-456-support-session"
) do |chunk|
case chunk["type"]
when "response"
print chunk["response"]
$stdout.flush
when "tool"
puts "\nCalling tool: #{chunk['tool']}"
when "usage"
puts "\n\nUsage: #{chunk['usage']}"
end
end
```
The stream yields the same event types documented in [Invoke Agent → Response](../api-reference/agents/invoke#response): `summary` (when auto-summarization fires), `reasoning`, `response`, `tool`, a final `usage` event, or an `error` event if the provider fails mid-stream.
If you omit the block, the method returns an `Enumerator` you can pass around:
```ruby theme={null}
enum = client.invoke_agent_stream(agent: "AGENT_UUID", message: "Hello")
enum.each { |chunk| handle(chunk) }
```
## Multi-turn conversations
### Persistent threads
Pass any string as `thread_id` and Fetch Hive will create the thread on the first call and resume it on subsequent calls with the same value:
```ruby theme={null}
client.invoke_agent(
agent: "AGENT_UUID",
message: "What are the main AI infrastructure trends right now?",
thread_id: "user-456-support-session"
)
client.invoke_agent(
agent: "AGENT_UUID",
message: "Which of those trends have the most enterprise adoption?",
thread_id: "user-456-support-session"
)
```
### Stateless history
Manage state yourself by passing the previous turns in `messages`. Fetch Hive uses the supplied history for context but does not persist it:
```ruby theme={null}
client.invoke_agent(
agent: "AGENT_UUID",
message: "Which of those trends have the most enterprise adoption?",
messages: [
{ role: "user", content: "What are the main AI infrastructure trends right now?" },
{ role: "assistant", content: "Teams are focusing on evals, tool routing, and observability." }
]
)
```
## Multimodal inputs
Attach images to the current message with `attachments`:
```ruby theme={null}
result = client.invoke_agent(
agent: "vision-agent",
message: "Describe this image",
attachments: ["https://example.com/photo.jpg"]
)
puts result["response"]
```
URLs must start with `https://`.
## Configuration
| Option | Default | Description |
| ---------- | ------------------------------ | ------------------------------- |
| `api_key` | `ENV["FETCH_HIVE_API_KEY"]` | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL |
| `timeout` | `120` | Request timeout in seconds |
```ruby theme={null}
client = FetchHive::Client.new(
api_key: "fhk_...",
base_url: "https://api.fetchhive.com/v1",
timeout: 120
)
```
## Errors
Non-2xx responses raise a `RuntimeError` with the status code and body. Rescue them if you need to handle failures:
```ruby theme={null}
begin
reply = client.invoke_agent(agent: "AGENT_UUID", message: "Hello")
rescue => e
warn "Fetch Hive error: #{e.message}"
end
```
See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for status code meanings.
## Links
* [Gem on RubyGems](https://rubygems.org/gems/fetch_hive)
* [Source on GitHub](https://github.com/Fetch-Hive/ruby-sdk)
## Next steps
* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Invoke Agent](../api-reference/agents/invoke) - Full endpoint reference
# Sub Agents
Source: https://docs.fetchhive.com/agents/sub-agents
Add another agent from the same workspace as a callable tool inside an agent
Sub agents let one agent call another active agent in the same workspace as a tool.
## Overview
You add sub agents from the same picker you use for MCP tools. After you attach one, it appears as its own node in the editor and gets its own settings sheet. This is useful when you want a parent agent to hand off a specific job to another agent instead of keeping all instructions in one place.
## How do I add a sub agent?
1. Open the parent agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In the picker, open **Sub Agents** and choose the child agent you want to attach.
4) Review or update **Tool Name**. Fetch Hive only allows lowercase letters, numbers, and underscores here.
5) Add a **Tool Description** that explains when the parent agent should use this sub agent.
6) Click **Add Sub Agent**.
The new sub agent appears as a node on the canvas as soon as Fetch Hive saves it.
## How do I configure a sub agent node?
1. Select the sub agent node in the editor.
2. Update **Tool Name** or **Tool Description** in the settings sheet if needed.
3. Click **Open in Editor** if you want to open the child agent in its own editor tab.
If you need to remove the sub agent, hover over its node and use the remove action. Fetch Hive asks you to confirm with **Remove sub agent?** and **Remove sub agent**.
## What limits should I know about?
Only other active agents in the same workspace appear in **Sub Agents**. Fetch Hive does not let you add the current agent as its own sub agent. If an agent is already attached, the picker shows it as unavailable instead of adding it again. Items marked **Soon** in the picker are not available yet.
For the main editor flow, see [Creating and Configuring](./creating-and-configuring). To test how a parent agent uses its sub agents, see [Testing with Chat](./testing-with-chat).
# Testing with Chat
Source: https://docs.fetchhive.com/agents/testing-with-chat
Test agent responses in the Fetch Hive editor before you invoke them from your own app
Use the editor's chat panel to test how an agent responds before you wire it into production traffic.
Looking for the full **Live Chat** product at [chat.fetchhive.com](https://chat.fetchhive.com) (saved conversations, models, agents, and tools)? See [Live Chat](../live-chat/overview).
## Overview
The **Chat** panel is built into the agent editor. It lets you send messages, inspect the response as it streams in, and clear the session when you want to start over. Messages in this panel are not saved.
The chat panel always tests the **saved** version of the agent. Any unsaved changes you have made in the editor — such as a different system prompt or model — will not be reflected until you save the agent first.
## How do I open the chat panel?
1. Open an agent in the editor.
2. Click **Chat** in the header.
The panel opens on the right with the title **Chat**. If you have not sent any messages yet, Fetch Hive shows **Test your agent** and the note that messages are not saved.
## How do I test an agent message?
1. Type your message into **Type a message...**.
2. Click **Attach file** to include CSV, XLSX, PDF, DOCX, or image files with the message. Image attachments require a vision-capable model.
3. Press Enter or click the send button.
4. Wait for the response to stream into the panel.
Click **Clear** when you want to remove the current test conversation and start fresh.
The paperclip also accepts MP3 and WAV audio up to 25 MB. Fetch Hive prepares a transcript first and disables send until it is ready. The chat model receives the transcript, not the raw audio.
Use **Use from this chat** to select an uploaded or generated artifact again without re-uploading it. The picker survives automatic text summarization. Clicking **Clear** removes both the test messages and this session's artifact list.
Document attachments are exposed to the agent through the system **File Tools**
MCP tool. The agent calls `read_file` when it needs the file contents. Images
are sent as image inputs when the selected model supports them.
## What can I learn from the chat output?
The panel shows the full conversation between you and the agent. When the agent reasons before answering or between response steps, Fetch Hive can show collapsible **Thinking** blocks inline with the rest of the message timeline. When the agent uses a tool, the panel can show tool cards such as **SERP API**, **Google Search**, **Vector Search**, **GPT Search**, or a named sub agent in the order they happened.
When usage data is available, Fetch Hive also shows badges for token count and duration under the response. Use this view to see whether the agent answered directly, used tools, or needed extra reasoning before it replied.
For editor setup, see [Creating and Configuring](./creating-and-configuring). If you want one agent to call another, see [Sub Agents](./sub-agents).
# Workflow Tools
Source: https://docs.fetchhive.com/agents/workflow-tools
Let an agent run a deployed workflow as a tool
Workflow tools let an agent call a deployed workflow endpoint variant during an agent run.
## Overview
Add a workflow tool when an agent should hand part of a task to an existing workflow. Fetch Hive starts the workflow as a normal workflow run, so it gets its own request ID, workflow run ID, workflow logs, and step trace. The parent agent also records the call as an agent tool span, with the workflow trace nested under that tool call in the agent run trace.
Workflow tools use the selected workflow endpoint variant's latest active version. The tool input schema is generated from the workflow's start input declarations, so the model can pass the same top-level inputs that the workflow expects from an API call.
## How do I add a workflow tool?
1. Open the parent agent in the agent editor.
2. Click the add-tool button in the editor header.
3. Choose a deployed workflow endpoint and variant from **Workflow Tools**.
4. Enter the tool name and description the model should see.
5. Save the tool.
The workflow endpoint and variant must belong to the same workspace as the agent. Tool names must be unique across the agent's MCP tools, workflow tools, and sub agents.
## What gets logged?
Every workflow tool call creates two linked records:
* A normal workflow run with its own request ID and workflow run ID.
* A parent agent tool call with metadata that identifies the workflow tool and the child workflow run.
You can inspect the child workflow from workflow logs exactly like any other workflow invocation. In the agent trace, the parent tool span is named `agent.tool.workflow`, and the child workflow spans are attached below that span.
## When should I use workflow tools?
Use workflow tools when the delegated work is already modeled as a workflow, especially if it includes multiple deterministic steps, branching, integrations, or reusable workflow-specific logging. Use sub agents when the delegated work should be handled by another agent with its own instructions and tool set.
# Agent quick start
Source: https://docs.fetchhive.com/getting-started/agent-quick-start
Create an agent, test it in chat, and invoke it through the public API
By the end of this guide, you'll have an agent configured in the dashboard, tested in chat, and ready to call through the public API.
## Prerequisites
* A Fetch Hive workspace
* A workspace API key if you want to run the public cURL example - see [API Keys](../workspace/api-keys)
## Step 1: Create an agent
Open **Agents** in the sidebar, then click **Add Agent**.
Enter a **Name**. If your workspace uses categories, you can also choose a **Category**. Click **Save** to open the agent editor.
## Step 2: Configure the root agent
In the editor, click the root agent node to open **Agent Settings**.
Add a short **Instruction Prompt** that tells the agent what to do. You can also confirm the **Model**, but you can keep the default settings for this first pass.
For example:
```text theme={null}
You are a research assistant. Answer clearly and keep responses brief unless the user asks for more detail.
```
## Step 3: Test the agent in chat
Click **Chat** in the editor header.
Send a short test message in the chat panel and confirm that the agent responds the way you expect.
This chat panel is for dashboard testing. The UI explicitly says these messages are not saved, so treat it as a safe place to iterate on behavior before you wire the agent into your app.
## Step 4: Copy the public invoke snippet
Open **Get Code** in the editor control bar, or use **More** in the sidebar and click **Get Code**.
Select your **Agent** and **API Key**. The dialog shows the public cURL example for `POST /v1/agent/invoke`.
The dialog provides a cURL snippet here. The **Python** and **TypeScript** tabs are still marked **Coming Soon**.
```bash theme={null}
curl 'https://api.fetchhive.com/v1/agent/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
"agent": "YOUR_AGENT_ID",
"message": "Summarize the latest AI infrastructure trends",
"streaming": true
}' \
--compressed
```
Replace `YOUR_API_KEY` and `YOUR_AGENT_ID` with your real values.
The in-app **Chat** panel uses a private dashboard testing flow. The snippet above is the public API flow you use outside the dashboard.
## Next steps
* [Agents](../agents/overview)
* [Creating and Configuring](../agents/creating-and-configuring)
* [Testing with Chat](../agents/testing-with-chat)
# Hive Agent Quick Start
Source: https://docs.fetchhive.com/getting-started/hive-agent-quick-start
Create a Hive Agent, configure budget guardrails, start a run, and inspect the result
By the end of this guide, you'll have a Hive Agent run that plans an objective, executes nodes, verifies output, and shows its result in logs.
## Prerequisites
* A Fetch Hive account ([sign up here](https://app.fetchhive.com))
* An active workspace **Default** API key - see [API Keys](../workspace/api-keys)
You can start Hive Agent runs from the dashboard or with the async public API. This quick start uses the dashboard flow first, then links to code invocation.
## Step 1: Create a Hive Agent
Open **Hive Agents** in the sidebar.
Click **New Agent Task**.
Rename the new Hive Agent from the breadcrumb menu.
## Step 2: Review the stage agents
Click **PLAN**, **EXECUTE**, and **VERIFY** on the canvas.
Confirm the model and runtime settings for each stage. Keep the defaults for your first run unless you already know a stage needs a different model.
## Step 3: Add executor tools
Click **EXECUTE**.
Use **Add Tool** to attach any tools the run needs, such as search, file, or integration tools.
Skip this step for a simple objective that the model can answer without tools.
## Step 4: Set budget guardrails
Click the dollar button in the editor control bar.
Set a **Budget Hint (USD)**, a **Budget Cap (USD)**, and **Budget Strictness**.
Keep **Max Concurrent Nodes** low for your first run if you want spending to be easier to watch.
## Step 5: Start a run
Click **Start Run**.
Enter a specific **Run objective**.
Add a **Website**, **File Upload**, **Knowledge Base**, or **Knowledge Base Item** source if the run needs grounding.
Click **Start Run**.
## Step 6: Open logs
Click **Logs** in the editor control bar, or open **Hive Agents** > **Logs**.
Find the run by Hive Agent name, objective, status, or request ID.
Click the row to open the detail sheet.
## Step 7: Read the result
Review the final response, source list, node overview, budget ledger, and trace.
If the objective asked for a spreadsheet or document, downloadable files appear with the final output when the run completes successfully.
If a node was rejected, read the rejection reason and tune the matching stage before starting another run.
## Next steps
* [Creating and Configuring](../hive-agents/creating-and-configuring)
* [Running Tasks](../hive-agents/running-tasks)
* [Invoke from Code](../hive-agents/invoke-from-code)
* [Logs](../hive-agents/logs)
* [Budget Approval](../hive-agents/budget-approval)
# Overview
Source: https://docs.fetchhive.com/getting-started/overview
Create your first prompt, workflow, agent, or Hive Agent and run it through Fetch Hive
Use these guides to get something working quickly in Fetch Hive. Prompt, workflow, chat Agent, and Hive Agent quick starts show how to move from dashboard setup to public API usage.
## What you'll find here
* [Prompt Quick Start](./prompt-quick-start) - Create a prompt, test it in the editor, deploy it, and copy a public invoke snippet
* [Workflow Quick Start](./workflow-quick-start) - Create a workflow, add a first step, run it, deploy it, and invoke it with cURL
* [Agent Quick Start](./agent-quick-start) - Create a chat Agent, test it in chat, and copy the public agent invoke snippet
* [Hive Agent Quick Start](./hive-agent-quick-start) - Create a Hive Agent, start a run, open logs, and learn the async public API path
# Prompt quick start
Source: https://docs.fetchhive.com/getting-started/prompt-quick-start
Create a prompt, test it in the editor, create a prompt deployment, and run it through the public API
By the end of this guide, you'll have a prompt running in the dashboard and a public cURL snippet you can use to invoke it from your app.
## Prerequisites
* A Fetch Hive workspace
* A workspace API key if you want to run the public cURL example - see [API Keys](../workspace/api-keys)
## Step 1: Create a prompt
Open **Prompts** in the sidebar, then click **Add Prompt**.
Enter a **Name**. If your workspace uses categories, you can also choose a **Category**. Click **Save** to open the editor.
## Step 2: Add your first message
In the editor, find the **Prompt** section and click **Add Message**.
For a minimal prompt, add one short instruction. For example:
```text theme={null}
You are a helpful assistant. Summarize the user's text in one sentence.
```
If you want the prompt to accept dynamic input, include a variable such as `{{text}}`. When your prompt contains variables, you can click **Variables** to open the **Input Values** sheet and provide test values before you run it.
### Using the dashboard copilot to draft a prompt
Instead of writing messages by hand, you can ask the dashboard copilot to draft a prompt for you (for example, "create a prompt that summarizes support tickets"). The copilot writes three messages instead of one:
1. A `system` message describing the assistant's objective, how it should handle edge cases, and how it stays on task.
2. A `user` message with **Instructions**, **Steps**, **Output Format**, **Examples**, and **Notes** sections written in Markdown.
3. When the prompt takes dynamic input, a final `user` message containing only the variable placeholders (for example `COMPANY_NAME:` followed by `{{company_name}}`), so the rest of the prompt never changes between runs.
Keeping the variables in their own trailing message lets Fetch Hive reuse the unchanged part of the prompt across calls, which reduces the input Fetch Hive needs to reprocess for the parts of the model that support prompt caching. You can edit any of these messages afterward like any other prompt message.
## Step 3: Test the prompt in the editor
Click **Run**.
The response appears in the **Model Response** area on the right side of the editor. Use this step to confirm that your prompt behaves the way you expect before you create a prompt deployment.
This in-editor run is for dashboard testing. It is not the same as the public API invoke flow.
## Step 4: Save a named version
Click **Save Version** in the editor header.
Enter a short description of what changed, then save the version. This gives you a named checkpoint you can refer back to later.
## Step 5: Create a deployment
Click **Deploy**, then choose **Create a Deployment**.
Enter a **Deployment key** and save it. This creates the live prompt deployment you can invoke outside the dashboard.
Use **Deploy** and **deployment** language here. In Fetch Hive, this is the step that makes your prompt available as a prompt deployment through the public API.
## Step 6: Copy the public invoke snippet
Open **More** in the sidebar, then click **Get Code**.
Select your **Deployment** and **Variant**. The dialog shows a cURL snippet for `POST /v1/prompt/invoke`.
The dialog provides a cURL snippet here. The **Python** and **TypeScript** tabs are still marked **Coming Soon**.
```bash theme={null}
curl 'https://api.fetchhive.com/v1/prompt/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
"deployment": "YOUR_DEPLOYMENT_NAME",
"variant": "YOUR_VARIANT_NAME",
"inputs": {
"text": "Fetch Hive helps teams ship AI products faster."
},
"streaming": true
}' \
--compressed
```
Replace `YOUR_API_KEY`, `YOUR_DEPLOYMENT_NAME`, `YOUR_VARIANT_NAME`, and the `inputs` object with your real values.
## Next steps
* [Prompts](../prompts/overview)
* [Publishing and Versioning](../prompts/publishing-and-versioning)
* [Run with API](../prompts/run-with-api)
# Workflow quick start
Source: https://docs.fetchhive.com/getting-started/workflow-quick-start
Create a workflow, run it in the editor, create a workflow deployment, and invoke it through the public API
By the end of this guide, you'll have a workflow running in the dashboard and a public cURL snippet you can use to invoke it from your app.
## Prerequisites
* A Fetch Hive workspace
* A workspace API key if you want to run the public cURL example - see [API Keys](../workspace/api-keys)
## Step 1: Create a workflow
Open **Workflows** in the sidebar, then click **Add Workflow**.
Enter a **Name**. If your workspace uses categories, you can also choose a **Category**. Click **Save** to open the workflow editor.
## Step 2: Add your first step
In the editor, click **Add Step** in the bottom control bar to append a step before **End**, or click the **+** connector between **Start** and **End** to insert a step between two nodes.
This opens **Search steps...**. Choose **AI Prompt** for the quickest possible first workflow.
When the new step appears on the canvas, click it to open **Step settings**.
## Step 3: Configure the step
Add a short instruction in **Step settings** so the workflow has something useful to do.
If your workflow needs input from the caller, define that input on the **Start** step first, then reference it inside your **AI Prompt** step.
Keep the first version simple. You do not need **Copilot**, advanced step types, or multiple branches for this quick start.
## Step 4: Run the workflow in the editor
Click **Run Workflow** in the bottom control bar.
This opens **Run History**. Click **Start** to open **Start a new Workflow Run**, then click **Start Workflow Run**.
This is a two-step flow in the UI. **Run Workflow** does not start the workflow immediately by itself.
## Step 5: Save a named version
Click **Save Version** in the bottom control bar.
Enter a description of what changed, then save the version. This gives you a named version you can refer back to later.
## Step 6: Create a deployment
Click **Deploy** in the bottom control bar, then choose **Create a Deployment**.
Enter a **Deployment key** and save it. This creates the live workflow deployment you can invoke through the public API.
## Step 7: Copy the public invoke snippet
Open **More** in the sidebar and click **Get Code**, or open **Code Snippet** from the deployment page.
Select your **Deployment** and **Variant**. The dialog shows a cURL snippet for `POST /v1/workflow/invoke`.
The public payload now uses `deployment` and `variant`, matching the language shown in the UI.
```bash theme={null}
curl 'https://api.fetchhive.com/v1/workflow/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
"deployment": "YOUR_DEPLOYMENT_NAME",
"variant": "YOUR_VARIANT_NAME",
"inputs": {
"topic": "State of enterprise AI in 2026"
}
}' \
--compressed
```
If you want Fetch Hive to return immediately and send the final result later, the UI supports a **Callback delivery** toggle in the code snippet dialog. That adds an `async` block with `enabled` and `callback_url`.
## Next steps
* [Workflows](../workflows/overview)
* [Workflow Steps](../workflows/steps/overview)
* [Publishing and Versioning](../workflows/publishing-and-versioning)
# Budget Approval
Source: https://docs.fetchhive.com/hive-agents/budget-approval
Approve or decline paused Hive Agent runs when budget guardrails require human review
Budget approval lets a Hive Agent pause before it keeps spending. The run waits for a recipient to approve more budget or decline the continuation.
## When does a run pause?
Fetch Hive checks budget before planning, again after source preparation, before each planner retry, and at the top of each repeat pass.
A run can pause when it crosses the **Budget Hint (USD)** and **Budget Strictness** is **Conservative**. **Balanced** usually continues but can reduce node concurrency after the hint is crossed. **Aggressive** allows more work before pausing.
A run can also stop when it reaches **Budget Cap (USD)** during plan, execute, or verify. The hard cap is the real ceiling by default for those stages.
If the Hive Agent is configured to ask for approval at the hard cap, the run pauses instead of stopping. **Compose always pauses for approval** when the hard cap would be exceeded, even if **When hard cap is reached** is **Stop run**. The approval page shows spend so far, the hard cap snapshot, the estimated next gated work, and a suggested additional budget amount.
When a run needs approval, its status becomes `blocked`. No new node work starts while the run waits.
## Who receives the approval?
Fetch Hive sends the approval to the Hive Agent creator when that person is still a member of the account. If not, it sends the approval to the account owner.
If **Email address** is set under **Notifications**, alerts go there. If **Send via** is **Telegram**, Fetch Hive sends to the selected connected Telegram account. The same delivery settings are used for budget approvals and optional run-finished alerts. If Telegram is selected but no active destination is available, Fetch Hive falls back to email.
## How do I approve more budget?
Open the approval page from the email or Telegram magic link, or click **Open budget approval** in the Hive Agent run console while the run is waiting.
Review the objective, spend summary, current hard cap, estimate, and expiry.
Enter **Additional budget (USD)** when you want to raise the cap.
Click **Approve and continue**.
Fetch Hive raises the hard cap by the additional amount and resumes the paused run.
For hard-cap approvals, **Additional budget (USD)** is required. For soft-hint approvals, it is optional.
## How do I decline?
Open the approval link and click **Decline**.
The run stays blocked and finalizes without continuing the loop.
## What happens when the link expires?
Budget approval links expire after 24 hours.
If the request can still be resent, click **Send a fresh link** from the expired page. Fetch Hive rotates the token and sends a new notification.
A newer pause can supersede an older pending approval. Use the newest link when multiple messages exist.
## How does approval affect the rest of the run?
After approval, Fetch Hive lets the current run continue past the soft hint. The hard cap still applies.
For hard-cap approvals, approval does not bypass the cap. Fetch Hive raises the cap by the amount you enter, then checks budget again before continuing. If the amount is too low, the run can pause again.
The projected amount is a token and rate-card estimate for the next gated work, not a guaranteed cost to finish. Retries, verifier rejections, and compose attempts can require more budget.
See also: [Creating and Configuring](./creating-and-configuring) for budget settings and [Notifications](./notifications) for all alert types.
# Clarification Requests
Source: https://docs.fetchhive.com/hive-agents/clarification
Answer a clarifying question when a Hive Agent pauses during planning
Sometimes a Hive Agent needs one clarifying answer before it can plan its work. When the objective is ambiguous, the run pauses and asks the recipient a short multiple-choice question.
## When does a run pause?
Fetch Hive asks for clarification only during **planning**, before any work nodes start. A run asks at most **one** question per run. The question can include up to four choices, and you can type a custom answer when that option is offered.
While waiting, the run status becomes `blocked`. No new node work starts until you answer or the request expires.
## Who receives the question?
Fetch Hive sends the clarification to the Hive Agent creator when that person is still a member of the account. If not, it sends the request to the account owner.
If **Email address** is set under **Notifications**, alerts go there. If **Send via** is **Telegram**, Fetch Hive sends to the selected connected Telegram account. If Telegram is selected but no active destination is available, Fetch Hive falls back to email.
## How do I answer?
Open the clarification page from the email or Telegram magic link, or click **Open clarification** in the Hive Agent run console while the run is waiting.
Review the objective and the question, choose an option (or enter a custom answer), then submit.
Fetch Hive resumes planning with your answer and continues the run.
## What happens when the link expires?
Clarification links expire after 24 hours.
If the request can still be resent, click **Send a fresh link** from the expired page. Fetch Hive rotates the token and sends a new notification.
If the request times out without an answer, the run stops and does not continue planning.
## How does clarification affect the rest of the run?
After you answer, Fetch Hive re-plans using your clarification and then executes the planned work nodes as usual.
Budget approval can still pause the same run later if spending crosses your budget guardrails. Clarification and budget approval are separate pauses.
See also: [Budget Approval](./budget-approval), [Notifications](./notifications), and [Running Tasks](./running-tasks).
# Creating and Configuring
Source: https://docs.fetchhive.com/hive-agents/creating-and-configuring
Create a Hive Agent blueprint, configure stage agents, tools, repeat and compose settings, and budget guardrails
Use the Hive Agent editor when you want a reusable blueprint for long-running work. The blueprint stores stage agents, tools, repeat settings, compose settings, and budget settings. Run objectives and sources are added later from **Start Run**.
## How do I create a Hive Agent?
Open **Hive Agents** in the sidebar.
Click **New Agent Task**.
Fetch Hive creates the blueprint and opens the canvas. Rename it from the breadcrumb menu when you want a clearer name.
Use the same breadcrumb menu to **Archive** a Hive Agent when you no longer need it. Archiving removes the blueprint from active Hive Agent lists and prevents new runs, but existing run records remain available in **Hive Agents** > **Logs**.
## Canvas stages
Every Hive Agent runs the same loop:
* **PLAN** breaks the run objective into nodes and defines what each node must produce
* **EXECUTE** runs those nodes and uses the tools you attach
* **VERIFY** checks each node output against the plan, source material, and verification criteria
* **REPEAT** sends rejected nodes back through execute and verify until the run passes or reaches your repeat settings
* **COMPOSE** assembles verified node outputs into the final response and checks that the response is faithful, complete, and in the requested format
The objective is per-run. Changing the blueprint changes future runs. Existing runs keep their original objective and sources.
## How do I configure stage agents?
Click **PLAN**, **EXECUTE**, **VERIFY**, or **COMPOSE** on the canvas to open that stage's settings.
Each stage has a dedicated agent behind it. You can configure runtime settings such as **Charge Type**, **Model**, temperature, reasoning, prompt cache, token limits, **Tool Choice**, **Max Tool Calls**, and MCP tools.
The stage instruction prompts are platform-owned. You do not edit the planner, executor, verifier, or composer instructions directly. Fetch Hive keeps those prompts fixed so the PLAN / EXECUTE / VERIFY / COMPOSE runtime stays compatible with the verifier and trace schema.
New Hive Agents use these defaults unless the workspace overrides them later:
| Stage | Default model | Default reasoning |
| ----------- | ------------- | ----------------- |
| **PLAN** | Claude Opus | High |
| **EXECUTE** | Gemini Flash | Low |
| **VERIFY** | Claude Opus | High |
| **COMPOSE** | Claude Opus | High |
If a stage model is retired, choose an active model before running the Hive Agent.
## How do tools work?
Open a stage settings sheet and click **Add Tool**.
Use **Tool Choice** to let the stage call tools automatically, require a tool call, or disable tool calls even when tools are attached. Use **Max Tool Calls** on OpenAI and xAI stages to send a provider-native tool/turn limit (`0` means unlimited). OpenAI maps the value to `max_tool_calls`; xAI maps it to `max_turns`. Anthropic, Gemini, and Perplexity stages do not show **Max Tool Calls**.
Tools are most useful on **EXECUTE**, because executor nodes are where the Hive Agent gathers data, searches, or calls integrations. **PLAN**, **VERIFY**, and **COMPOSE** can also expose supported tools when the tool is compatible with that stage and model provider.
System `file_tools` are not sent on **PLAN**, **EXECUTE**, **VERIFY**, or **COMPOSE** invokes — those stages ground Knowledge Base / uploaded sources via platform retrieval (`SOURCE CONTEXT`). When a run asks for a downloadable spreadsheet or document, Fetch Hive builds the file after compose and attaches it to the run result. Fix empty source context by adjusting Knowledge Base threshold/chunking (see [Testing and Iteration](./testing-and-iteration#large-source-objectives)), not by attaching file tools to the executor.
Some tools have their own settings. Click an attached tool row to open its settings, such as search context size, location, or allowed domains. If you change a stage model to a provider that cannot use an attached tool, the tool remains attached and is marked **Tool not supported** until you remove it or choose a compatible model.
Some tools that exist for chat Agents are hidden for Hive Agents when they do not fit the stage runtime.
## How do I configure repeat settings?
Click **REPEAT** on the canvas.
Set **Max repeat passes** to control how many full execute-and-verify passes the run can make.
Set **Max compose attempts** to control how many times the final response can be rebuilt after all required nodes are verified. Compose retries do not send node work back through repeat.
Budget is checked before each compose attempt, so conservative budget strictness can pause a run during Compose even after all required nodes are verified.
Set **Completion mode**:
* **Strict** fails the run if required nodes still cannot be verified
* **Best effort** completes with verified work and flags anything still unverified. After the pass limit, it still runs **COMPOSE** from any verified nodes so you get a partial final response when possible
Best effort is useful when you prefer partial verified output over a failed run after the pass limit.
Best effort only softens node verification exhaustion. If final composition cannot pass after **Max compose attempts**, the run fails.
## Editor control bar
The Hive Agent editor keeps run and blueprint actions in the bottom control bar:
* **Start Run** — start a dashboard run. While any run is still live (including a budget pause awaiting approval), this control shows the live status instead. A terminal **Budget stop** (`budget_block_state: stopped`) is finished, so **Start Run** returns and you can start another run.
* **Budget Settings** (dollar button) — budget hint, cap, strictness, and concurrency
* **Notifications** (bell) — email/Telegram delivery and run-finished alerts
* **Get Code** — copy the public invoke snippet
* **Logs** — open Hive Agent run history
## How do I configure budget settings?
Click the dollar button in the editor control bar to open **Budget Settings**.
Configure:
* **Budget Hint (USD)** - soft threshold for warnings or approval prompts
* **Budget Cap (USD)** - hard ceiling for the run
* **When hard cap is reached** - choose **Stop run** or **Ask for approval** for plan and execute. Compose always pauses for approval if the hard cap would be exceeded.
* **Budget Strictness** - **Conservative**, **Balanced**, or **Aggressive**
* **Max Concurrent Nodes** - maximum executor nodes the planner may create and how many can run in parallel during execute/verify, from 1 to 10
Higher concurrency can finish faster and spend faster. Conservative budget strictness pauses earlier. Balanced strictness can throttle work after the hint is crossed. Aggressive strictness lets more work continue before pausing.
Click the bell button in the editor control bar to open **Notifications**. Use it to choose **Send via** Email/Telegram, set an optional delivery destination, and turn on **Notify when run finishes** for future dashboard runs.
See also: [Running Tasks](./running-tasks), [Budget Approval](./budget-approval), and [Notifications](./notifications).
# Invoke from Code
Source: https://docs.fetchhive.com/hive-agents/invoke-from-code
Start Hive Agent runs from the API with callback delivery
Use the public API when your app needs to start a Hive Agent run outside the dashboard. The API starts the run asynchronously, returns identifiers immediately, and sends a signed callback when the run finishes.
For the full endpoint reference — request body, callbacks, and examples — see [Invoke](../api-reference/hive-agents/invoke) in the API Reference.
Hive Agent invocation does not stream and does not wait for the final answer in the HTTP response. Open [Logs](./logs) to inspect status, trace, costs, node output, partial results, callback attempts, and the final response.
## Next steps
* [Invoke](../api-reference/hive-agents/invoke) — API Reference endpoint
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Running Tasks](./running-tasks)
* [Logs](./logs)
* [Budget Approval](./budget-approval)
# Logs
Source: https://docs.fetchhive.com/hive-agents/logs
Inspect Hive Agent run history, statuses, traces, nodes, costs, sources, and partial results
Hive Agent logs show every workspace Hive Agent run in one table and let you inspect the run's trace, nodes, sources, budget ledger, and final response.
## How do I open Hive Agent logs?
From the Hive Agent editor, click **Logs** in the bottom control bar.
Or open **Hive Agents** in the sidebar and click **Logs** in the secondary navigation.
Hive Agent logs use a workspace-wide run table and include **Source** navigation for **All Sources**, **Dashboard**, and **API** runs.
## How do I filter logs?
Use the date-range control, pagination, column visibility, and table filters.
Hive Agent logs support:
* **Hive Agent**
* **Status**
* **Source** navigation for **All Sources**, **Dashboard**, and **API**
* Text search by Hive Agent name, objective, or request ID
The table includes **Hive Agent**, **Objective**, **Status**, **Pass**, **Nodes**, **Sources**, **Total Tokens**, **Total Cost**, **Duration**, **API Key**, and **Collaborator**. Hover the tokens, tasks, or cost totals to open the stage usage breakdown: one **Plan** row aggregates planner validation retries with nested **Attempt #1**, **Attempt #2**, and so on, while execute/verify node attempts keep their pass labels.
## What is the difference between pass and attempt?
A **pass** is one full execute-and-verify round for the run. If one or more nodes are rejected, Hive Agents can start another pass for the work that still needs fixing.
An **attempt** is a specific execute or verify try for an individual node. A node can show multiple attempts when it is executed, checked, rejected, and retried.
In the Run Console, a node can show **Pending verification** after its execute attempt has completed but before the verifier has started. Retried nodes also move out of **Failed** while the run is actively executing or verifying them again on a later pass, using live attempt and pass data rather than the last stored failure row.
**Compose attempts** are separate from node attempts. Compose attempts rebuild and check the final response after the required node work has already been verified.
Example: if Pass 1 verifies two nodes and rejects one node, Pass 2 retries the rejected node. That retried node may show several attempts because each execute or verify try is recorded.
## Status glossary
| Status | Meaning |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending` | The run has been created and is waiting to start |
| `preparing_sources` | Fetch Hive is processing website or file sources before planning |
| `planning` | The planner is turning the objective into nodes and verification criteria |
| `executing` | Executor agents are working on nodes |
| `verifying` | The verifier is checking node outputs |
| `retrying` | Rejected nodes are being prepared for another pass |
| `composing` | The composer is assembling and checking the final response |
| `blocked` | The run paused for a human decision — budget approval or planner clarification. Use `budget_block_state` and `clarification_block_state` to tell them apart: `awaiting_approval` / `awaiting_clarification` means the workflow is still waiting (`ended_at` is null); `stopped` means that HITL path finished and `ended_at` is set (budget hard cap / approval declined or expired, or clarification timed out). Only one of the two `*_block_state` fields is `stopped` for a given terminal stop |
| `completed` | The run finished successfully, or finished best-effort with unverified nodes flagged |
| `failed` | The run could not complete |
| `cancelling` | Cancellation has been requested |
| `cancelled` | The run stopped by cancellation |
## How do I cancel a running Hive Agent?
While a run is active, open the **Run Console** from Hive Agent logs or open the run from **request detail** (global search, experiments, or the technical trace sheet).
Click **Cancel run** in the sheet header and choose how to stop:
* **Stop now** — stops immediately and marks remaining work cancelled
* **Stop and keep verified work** — stops scheduling new work, lets in-flight steps finish, and keeps verified node output
The status moves to `cancelling` while the run drains, then `cancelled` when finished. See [Troubleshooting — cancelled](./troubleshooting#cancelled) for hard-stop vs partial-result behavior.
## How do I read the detail sheet?
Click a run row.
The root run overview keeps the final response, source list, node overview, budget ledger, and run config together.
The final response prefers the accepted composed response when one is available. Verified node outputs remain available as supporting detail. In best-effort mode, unverified nodes stay flagged so you can see what did not pass.
On completed or failed output, use the thumbs up/down control to rate the result and optionally describe what went wrong.
Node details can show output, rejection reasons, verification checks, pass number, cost, tokens, and linked child AgentRun details.
The Run Console shows separate banners for **awaiting approval** (you can approve to continue) versus **stopped on budget** (the run is finished). The stopped banner uses the blocking gate event when available: it distinguishes spend that already hit the cap from blocks where the next step's projected cost would exceed the cap, and it uses the cap recorded at block time rather than a later blueprint value. Budget spend in the console uses `cumulative_cost_usd` — the same figure `BudgetGate` enforces — not the plan-time `projected_cost_usd` estimate.
## How do traces work?
Hive Agent traces show the loop as a waterfall:
* Source preparation
* Planning
* Execution
* Verification
* Repeat decisions
* Compose attempts
* Budget checks and budget events
* Retryable stage errors
* Final completion, failure, or cancellation
Compose spans appear as soon as composition starts, not only after the composer finishes. While a compose attempt is running, the run status is `composing` and `run_config.composition.status` is `running`.
Execute and verify spans also appear while each node stage is running (`status: running`), then complete on the same span row when the stage finishes. Execute, verify, compose, and compose verify are sibling root-level spans; imported child AgentRun details stay nested under their own stage anchor. The waterfall orders spans by lifecycle phase and pass (`order_pass`, `order_phase`, node position, execute-before-verify), not wall-clock start time alone — so prepare, pre-plan budget gates, plan, per-pass budget gates, execute nodes, verify nodes, compose, compose verify, and terminal spans stay readable even when child traces finish at different times. Compose stage spans keep the full attempt envelope while imported composer child spans are scaled to fill that window.
Budget spans (`agent_task.budget_gate_check`, `agent_task.budget_step_cost`, `agent_task.budget_threshold_crossed`) are semantic markers anchored to stage start or end — not separate work units. Per-node execute gates nest under their `execute_node` row; step costs and threshold crossings appear at the end of the stage envelope. Pass-level gates stay at the root but align to the earliest execute in that pass.
When verify fails before semantic checks (for example `failure_reason: no_execute_attempt`), the verify span input includes `wired_execute_attempt_id` from the workflow handoff for debugging. Execute and verify stage span metadata also carries `stage_pair_key` (`{node_id}-p{pass}-a{attempt}`), `paired_span_id` (the counterpart span id), and `verify_attempt_id` on the execute row after verify finishes. Older traces can backfill these fields via `agent_tasks:repair_trace_lifecycle`.
Select a stage to see its **Input**, **Output**, and **Metadata**. Failed, blocked, or retryable stages show an issue alert. Budget spans show budget settings in the span header, and repeat spans show repeat settings there. A run-level failure message appears on the run overview and terminal spans, while allowed budget checks stay informational.
Planner, executor, verifier, and composer calls can expand to show their child AgentRun trace inline, including model reasoning, LLM responses, and tool input and response panels. Use the child request link when you need to open that exact run separately.
## What happens after partial-result cancellation?
A partial-result cancellation stops new node work, lets already-started node work drain, and stores verified node output in the run details.
The run status is still `cancelled`, but the verified partial result remains available from the detail sheet.
See also: [Log History](../monitoring/log-history) and [Troubleshooting](./troubleshooting).
# Notifications
Source: https://docs.fetchhive.com/hive-agents/notifications
Email and Telegram alerts for budget pauses and finished Hive Agent runs
Hive Agents can send four kinds of dashboard alerts. All of them reuse the same **Notifications** delivery settings on the Hive Agent blueprint: **Send via** (Email or Telegram), optional **Email address**, and optional **Telegram account**.
These alerts are separate from [public API callbacks](./invoke-from-code). Callbacks are HTTPS webhooks for code integrations. Dashboard notifications are email or Telegram messages for people working in Fetch Hive.
## Comparison
| Alert | When it sends | Opt-in? | Link in message |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------- |
| **Clarification request** | Run pauses during planning because the objective needs one clarifying answer | Always when the run pauses | Magic link to the [clarification](./clarification) page |
| **Budget hint approval** | Run pauses after crossing **Budget Hint** under conservative or balanced strictness | Always when the run pauses | Magic link to the [budget approval](./budget-approval) page |
| **Hard cap approval** | Run pauses at **Budget Cap** when **When hard cap is reached** is **Ask for approval**, or always when Compose would exceed the hard cap | Always when the run pauses | Same magic-link approval page |
| **Run finished** | Run reaches `completed`, `failed`, or `cancelled` | Off by default; enable per blueprint or per run | Deep link to the run in [Logs](./logs) |
## Who receives alerts?
**Clarification requests** and **budget approvals** go to the Hive Agent creator when that person is still an account member. If not, Fetch Hive uses the account owner.
**Run finished** alerts prefer the dashboard user who started the run. If the run was started without a user (for example from the public API), Fetch Hive falls back to the same creator → account owner rule.
If **Email address** is set under **Notifications**, alerts go there. Otherwise Fetch Hive uses the resolved recipient's account email.
## Configure delivery
Open the Hive Agent editor and click the bell button in the editor control bar to open **Notifications**.
* **Notify when run finishes** — task-level default for run-finished alerts (off by default)
* **Send via** — **Email** or **Telegram**
* **Email address** or **Telegram account** — optional override for where alerts are delivered
If **Send via** is **Telegram** but no active Telegram destination is available, Fetch Hive falls back to email.
See [Creating and Configuring](./creating-and-configuring) for the Budget Settings and Notifications controls.
## Clarification request
This alert fires when planning cannot continue until a person answers one clarifying question.
The message includes the objective and a link to the clarification page. While waiting, the run status is `blocked`. See [Clarification Requests](./clarification) for answer, expiry, and resend behavior.
## Budget hint approval
This alert fires when a run crosses the **Budget Hint (USD)** and Fetch Hive pauses for human review.
Typical causes:
* **Budget Strictness** is **Conservative** — Fetch Hive pauses soon after the hint is crossed
* **Budget Strictness** is **Balanced** — the run may continue with lower concurrency first, then pause if spending keeps rising
The message summarizes spend against the hint. **Additional budget (USD)** is optional on the approval page.
While waiting, the run status is `blocked`. See [Budget Approval](./budget-approval) for approve, decline, expiry, and resend behavior.
## Hard cap approval
This alert fires when cumulative spend plus projected next gated work reaches the **Budget Cap (USD)** and either **When hard cap is reached** is **Ask for approval**, or the pause is at Compose (Compose always asks for approval at the hard cap, even under **Stop run**).
The message includes:
* Spend so far against the hard cap
* Estimated cost for the next gated work
* A suggested additional budget amount
**Additional budget (USD)** is required on the approval page for hard-cap pauses.
Approval raises the cap by the amount you enter, then budget is checked again before work continues. If the amount is too low, the run can pause again.
## Run finished
This alert fires when a run reaches a terminal status:
* `completed`
* `failed`
* `cancelled`
It does **not** fire when a run is `blocked` waiting for budget approval or clarification — those alerts already went out.
### Task default
In **Notifications**, turn on **Notify when run finishes** to make this the default for future dashboard runs.
### Per-run override
In **Start Run**, use **Notify me when this run finishes** to override the task default for one execution. See [Running Tasks](./running-tasks).
The message matches the budget-approval email layout: heading, short status summary (including the Hive Agent name), objective, total spend, and a **View run log** link to open the run in [Logs](./logs).
See also: [Clarification Requests](./clarification), [Budget Approval](./budget-approval), [Running Tasks](./running-tasks), and [Logs](./logs).
# Overview
Source: https://docs.fetchhive.com/hive-agents/overview
Build durable Hive Agents that plan, execute, verify, repeat, and compose long-running work from the dashboard or public API
Hive Agents are dashboard-built agents for larger objectives that need planning, source context, verification, retries, final-response composition, and budget guardrails.
A Hive Agent is a reusable blueprint. Each **Start Run** creates a new run with its own objective, sources, status, trace, costs, nodes, and final response. The runtime may take minutes or days depending on the task.
Use a chat Agent when you need one assistant you can test and invoke from code. Use a Workflow when you need a fixed sequence of steps. Use a Hive Agent when you want Fetch Hive to break one objective into work nodes, execute them with tools, verify the outputs, repeat weak work until it passes or reaches your limits, and compose the verified work into one final response.
Hive Agents can be started from the dashboard or invoked from code. Public API invocation starts an async run; inspect progress, costs, traces, and final responses in Hive Agent logs.
## What you'll find here
* [Creating and Configuring](./creating-and-configuring) - Create a Hive Agent, configure stage agents, repeat settings, budget settings, and tools
* [Running Tasks](./running-tasks) - Start a run with an objective and optional sources
* [Invoke from Code](./invoke-from-code) - Start an async Hive Agent run with the public API
* [Budget Approval](./budget-approval) - Review paused runs that need more budget before they continue
* [Clarification Requests](./clarification) - Answer a clarifying question when planning needs more detail
* [Notifications](./notifications) - Email and Telegram alerts for clarification, budget pauses, and finished runs
* [Testing and Iteration](./testing-and-iteration) - Tune runs by reading verifier feedback and completion outcomes
* [Logs](./logs) - Inspect Hive Agent run history, traces, node output, and partial results
* [Troubleshooting](./troubleshooting) - Fix common setup, source, budget, and trace issues
# Run with Node.js SDK
Source: https://docs.fetchhive.com/hive-agents/run-with-nodejs-sdk
Start a Hive Agent run from Node.js or TypeScript with the @fetch-hive/sdk package
Use the official `@fetch-hive/sdk` package when you want to start a Hive Agent run from Node.js or TypeScript. The SDK wraps the public [`POST /v1/hive-agent/invoke`](../api-reference/hive-agents/invoke) endpoint with a typed client and handles authentication.
Hive Agent invocation does not stream and does not wait for the final answer in the HTTP response. The SDK returns identifiers immediately, then Fetch Hive sends a signed callback when the run completes, fails, or is cancelled.
## Installation
```bash theme={null}
npm install @fetch-hive/sdk
# or
yarn add @fetch-hive/sdk
# or
pnpm add @fetch-hive/sdk
```
The SDK targets Node.js 18+ (it uses the global `fetch`) and ships with TypeScript types out of the box.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key:
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```typescript theme={null}
import { FetchHive } from '@fetch-hive/sdk';
const client = new FetchHive();
```
Or pass the key explicitly:
```typescript theme={null}
const client = new FetchHive({ apiKey: 'fhk_...' });
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Start a Hive Agent run and read the accepted response:
```typescript theme={null}
import { FetchHive } from '@fetch-hive/sdk';
const client = new FetchHive();
const result = await client.invokeHiveAgent({
hive_agent: 'YOUR_HIVE_AGENT_ID',
objective: 'Research competitors and summarize verified findings',
callback_url: 'https://example.com/hive-agent-callback',
sources: {
website_urls: ['https://example.com'],
},
metadata: { customer_id: 'cus_123' },
});
console.log(result.run_id);
console.log(result.request_id);
console.log(result.webhook_secret);
```
`invokeHiveAgent` returns a `Promise` that resolves to the parsed JSON body as soon as the run is queued. See the [accepted response shape](../api-reference/hive-agents/invoke#response).
## Method reference
| Field | Type | Required | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `hive_agent` | `string` | Yes | The Hive Agent ID from the dashboard |
| `objective` | `string` | Yes | Specific objective for the planner to create work nodes from |
| `callback_url` | `string` | Yes | HTTPS URL that receives the signed terminal callback |
| `sources` | `{ website_urls?: string[]; asset_ids?: string[]; knowledge_base_ids?: string[]; knowledge_base_item_ids?: string[] }` | No | Grounded context from websites, assets, or knowledge bases in the workspace |
| `metadata` | `Record` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
The SDK always sends `async.enabled: true` with your `callback_url`. Hive Agent invocation is async-only.
## Handling the response
Fetch Hive returns `202 Accepted` when the run is queued. Store `webhook_secret` so your callback receiver can verify `X-Fetch-Hive-Signature`.
```typescript theme={null}
const result = await client.invokeHiveAgent({
hive_agent: 'YOUR_HIVE_AGENT_ID',
objective: 'Research competitors and summarize verified findings',
callback_url: 'https://example.com/hive-agent-callback',
});
console.log(result.run_id); // queued run identifier
console.log(result.request_id); // use this to look up the run in Logs
console.log(result.status); // usually "pending"
console.log(result.webhook_secret); // verify the signed callback
```
Open [Logs](./logs) to inspect status, trace, costs, node output, callback attempts, and the final response.
## Configuration
| Option | Default | Description |
| --------- | -------------------------------- | ------------------------------- |
| `apiKey` | `process.env.FETCH_HIVE_API_KEY` | Bearer token from the dashboard |
| `baseURL` | `https://api.fetchhive.com/v1` | Override the API base URL |
```typescript theme={null}
const client = new FetchHive({
apiKey: 'fhk_...',
baseURL: 'https://api.fetchhive.com/v1',
});
```
## Errors
Missing `callback_url` throws before a request is sent. Non-2xx responses throw an `Error` whose message includes the status code and response body:
```typescript theme={null}
try {
const result = await client.invokeHiveAgent({
hive_agent: 'YOUR_HIVE_AGENT_ID',
objective: 'Research competitors and summarize verified findings',
callback_url: 'https://example.com/hive-agent-callback',
});
} catch (err) {
console.error('Fetch Hive error:', err);
}
```
See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for status code meanings.
## Links
* [Package on npm](https://www.npmjs.com/package/@fetch-hive/sdk)
* [Source on GitHub](https://github.com/Fetch-Hive/nodejs-sdk)
## Next steps
* [Invoke from Code](./invoke-from-code) - Overview of starting runs from your app
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Invoke](../api-reference/hive-agents/invoke) - Full endpoint reference
# Run with PHP SDK
Source: https://docs.fetchhive.com/hive-agents/run-with-php-sdk
Start a Hive Agent run from PHP with the fetch-hive/sdk Composer package
Use the official `fetch-hive/sdk` Composer package when you want to start a Hive Agent run from PHP. The SDK wraps the public [`POST /v1/hive-agent/invoke`](../api-reference/hive-agents/invoke) endpoint with an idiomatic facade and handles authentication.
Hive Agent invocation does not stream and does not wait for the final answer in the HTTP response. The SDK returns identifiers immediately, then Fetch Hive sends a signed callback when the run completes, fails, or is cancelled.
## Installation
```bash theme={null}
composer require fetch-hive/sdk
```
The SDK requires PHP 8.1+ and uses Guzzle as its HTTP client.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the client reads it automatically):
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```php theme={null}
'fhk_...']);
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Start a Hive Agent run and read the accepted response:
```php theme={null}
invokeHiveAgent([
'hive_agent' => 'YOUR_HIVE_AGENT_ID',
'objective' => 'Research competitors and summarize verified findings',
'callback_url' => 'https://example.com/hive-agent-callback',
'sources' => ['website_urls' => ['https://example.com']],
'metadata' => ['customer_id' => 'cus_123'],
]);
echo $result['run_id'];
echo $result['request_id'];
echo $result['webhook_secret'];
```
`invokeHiveAgent` returns the parsed JSON body as an associative array as soon as the run is queued. See the [accepted response shape](../api-reference/hive-agents/invoke#response).
## Method reference
| Key | Type | Required | Description |
| -------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `hive_agent` | `string` | Yes | The Hive Agent ID from the dashboard |
| `objective` | `string` | Yes | Specific objective for the planner to create work nodes from |
| `callback_url` | `string` | Yes | HTTPS URL that receives the signed terminal callback |
| `sources` | `array` | No | Grounded context from websites, assets, or knowledge bases in the workspace |
| `metadata` | `array` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
The SDK always sends `async.enabled: true` with your `callback_url`. Hive Agent invocation is async-only.
## Handling the response
Fetch Hive returns `202 Accepted` when the run is queued. Store `webhook_secret` so your callback receiver can verify `X-Fetch-Hive-Signature`.
```php theme={null}
$result = $client->invokeHiveAgent([
'hive_agent' => 'YOUR_HIVE_AGENT_ID',
'objective' => 'Research competitors and summarize verified findings',
'callback_url' => 'https://example.com/hive-agent-callback',
]);
echo $result['run_id']; // queued run identifier
echo $result['request_id']; // use this to look up the run in Logs
echo $result['status']; // usually "pending"
echo $result['webhook_secret']; // verify the signed callback
```
Open [Logs](./logs) to inspect status, trace, costs, node output, callback attempts, and the final response.
## Configuration
| Option | Default | Description |
| ---------- | ------------------------------ | ------------------------------- |
| `api_key` | `FETCH_HIVE_API_KEY` env var | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL |
| `timeout` | `120` | Request timeout in seconds |
```php theme={null}
$client = new FetchHive([
'api_key' => 'fhk_...',
'base_url' => 'https://api.fetchhive.com/v1',
'timeout' => 60.0,
]);
```
## Errors
Missing `callback_url` throws `InvalidArgumentException` before a request is sent. Non-2xx responses throw `FetchHive\Sdk\Exception\ApiException` carrying the status code and response body:
```php theme={null}
use FetchHive\Sdk\Exception\ApiException;
try {
$result = $client->invokeHiveAgent([
'hive_agent' => 'YOUR_HIVE_AGENT_ID',
'objective' => 'Research competitors and summarize verified findings',
'callback_url' => 'https://example.com/hive-agent-callback',
]);
} catch (ApiException $e) {
error_log('Fetch Hive error: ' . $e->getMessage());
}
```
See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for status code meanings.
## Links
* [Package on Packagist](https://packagist.org/packages/fetch-hive/sdk)
* [Source on GitHub](https://github.com/Fetch-Hive/php-sdk)
## Next steps
* [Invoke from Code](./invoke-from-code) - Overview of starting runs from your app
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Invoke](../api-reference/hive-agents/invoke) - Full endpoint reference
# Run with Python SDK
Source: https://docs.fetchhive.com/hive-agents/run-with-python-sdk
Start a Hive Agent run from Python with the fetch-hive-sdk package
Use the official `fetch-hive-sdk` package when you want to start a Hive Agent run from Python. The SDK wraps the public [`POST /v1/hive-agent/invoke`](../api-reference/hive-agents/invoke) endpoint with an idiomatic helper and handles authentication.
Hive Agent invocation does not stream and does not wait for the final answer in the HTTP response. The SDK returns identifiers immediately, then Fetch Hive sends a signed callback when the run completes, fails, or is cancelled.
## Installation
```bash theme={null}
pip install fetch-hive-sdk
```
The SDK requires Python 3.9+ and uses `httpx` under the hood.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the SDK reads it automatically):
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```python theme={null}
from fetch_hive_sdk import FetchHive
client = FetchHive()
```
Or pass the key explicitly:
```python theme={null}
client = FetchHive(api_key="fhk_...")
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Start a Hive Agent run and read the accepted response:
```python theme={null}
from fetch_hive_sdk import FetchHive
client = FetchHive()
result = client.invoke_hive_agent(
hive_agent="YOUR_HIVE_AGENT_ID",
objective="Research competitors and summarize verified findings",
callback_url="https://example.com/hive-agent-callback",
sources={"website_urls": ["https://example.com"]},
metadata={"customer_id": "cus_123"},
)
print(result["run_id"])
print(result["request_id"])
print(result["webhook_secret"])
```
`invoke_hive_agent` is synchronous and returns the parsed JSON body as soon as the run is queued. See the [accepted response shape](../api-reference/hive-agents/invoke#response).
## Method reference
| Argument | Type | Required | Description |
| -------------- | ------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `hive_agent` | `str` | Yes | The Hive Agent ID from the dashboard |
| `objective` | `str` | Yes | Specific objective for the planner to create work nodes from |
| `callback_url` | `str` | Yes | HTTPS URL that receives the signed terminal callback |
| `sources` | `dict` | No | Grounded context from websites, assets, or knowledge bases in the workspace |
| `metadata` | `dict[str, str \| int \| float \| bool \| None]` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
The SDK always sends `async.enabled: true` with your `callback_url`. Hive Agent invocation is async-only.
## Handling the response
Fetch Hive returns `202 Accepted` when the run is queued. Store `webhook_secret` so your callback receiver can verify `X-Fetch-Hive-Signature`.
```python theme={null}
result = client.invoke_hive_agent(
hive_agent="YOUR_HIVE_AGENT_ID",
objective="Research competitors and summarize verified findings",
callback_url="https://example.com/hive-agent-callback",
)
print(result["run_id"]) # queued run identifier
print(result["request_id"]) # use this to look up the run in Logs
print(result["status"]) # usually "pending"
print(result["webhook_secret"]) # verify the signed callback
```
Open [Logs](./logs) to inspect status, trace, costs, node output, callback attempts, and the final response.
## Configuration
| Option | Default | Description |
| ---------- | ------------------------------ | ------------------------------- |
| `api_key` | `FETCH_HIVE_API_KEY` env var | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL |
| `timeout` | `120` | Request timeout in seconds |
```python theme={null}
client = FetchHive(
api_key="fhk_...",
base_url="https://api.fetchhive.com/v1",
timeout=60,
)
```
## Errors
Missing `callback_url` raises `ValueError` before a request is sent. Non-2xx responses raise an `httpx.HTTPStatusError` with the status code and response body:
```python theme={null}
import httpx
try:
result = client.invoke_hive_agent(
hive_agent="YOUR_HIVE_AGENT_ID",
objective="Research competitors and summarize verified findings",
callback_url="https://example.com/hive-agent-callback",
)
except httpx.HTTPStatusError as exc:
print("Fetch Hive returned", exc.response.status_code, exc.response.text)
```
See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for status code meanings.
## Links
* [Package on PyPI](https://pypi.org/project/fetch-hive-sdk/)
* [Source on GitHub](https://github.com/Fetch-Hive/python-sdk)
## Next steps
* [Invoke from Code](./invoke-from-code) - Overview of starting runs from your app
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Invoke](../api-reference/hive-agents/invoke) - Full endpoint reference
# Run with Ruby SDK
Source: https://docs.fetchhive.com/hive-agents/run-with-ruby-sdk
Start a Hive Agent run from Ruby with the fetch_hive gem
Use the official `fetch_hive` gem when you want to start a Hive Agent run from Ruby. The SDK wraps the public [`POST /v1/hive-agent/invoke`](../api-reference/hive-agents/invoke) endpoint with an idiomatic helper and handles authentication.
Hive Agent invocation does not stream and does not wait for the final answer in the HTTP response. The SDK returns identifiers immediately, then Fetch Hive sends a signed callback when the run completes, fails, or is cancelled.
## Installation
Add to your `Gemfile`:
```ruby theme={null}
gem "fetch_hive"
```
Then run:
```bash theme={null}
bundle install
```
Or install directly:
```bash theme={null}
gem install fetch_hive
```
The gem uses `faraday` under the hood and supports Ruby 3.0+.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the client reads it automatically):
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```ruby theme={null}
require "fetch_hive"
client = FetchHive::Client.new
```
Or pass the key explicitly:
```ruby theme={null}
client = FetchHive::Client.new(api_key: "fhk_...")
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Start a Hive Agent run and read the accepted response:
```ruby theme={null}
require "fetch_hive"
client = FetchHive::Client.new
result = client.invoke_hive_agent(
hive_agent: "YOUR_HIVE_AGENT_ID",
objective: "Research competitors and summarize verified findings",
callback_url: "https://example.com/hive-agent-callback",
sources: { website_urls: ["https://example.com"] },
metadata: { customer_id: "cus_123" }
)
puts result["run_id"]
puts result["request_id"]
puts result["webhook_secret"]
```
`invoke_hive_agent` returns the parsed JSON body as a hash as soon as the run is queued. See the [accepted response shape](../api-reference/hive-agents/invoke#response).
## Method reference
| Keyword | Type | Required | Description |
| -------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `hive_agent` | `String` | Yes | The Hive Agent ID from the dashboard |
| `objective` | `String` | Yes | Specific objective for the planner to create work nodes from |
| `callback_url` | `String` | Yes | HTTPS URL that receives the signed terminal callback |
| `sources` | `Hash` | No | Grounded context from websites, assets, or knowledge bases in the workspace |
| `metadata` | `Hash` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
The SDK always sends `async.enabled: true` with your `callback_url`. Hive Agent invocation is async-only.
## Handling the response
Fetch Hive returns `202 Accepted` when the run is queued. Store `webhook_secret` so your callback receiver can verify `X-Fetch-Hive-Signature`.
```ruby theme={null}
result = client.invoke_hive_agent(
hive_agent: "YOUR_HIVE_AGENT_ID",
objective: "Research competitors and summarize verified findings",
callback_url: "https://example.com/hive-agent-callback"
)
puts result["run_id"] # queued run identifier
puts result["request_id"] # use this to look up the run in Logs
puts result["status"] # usually "pending"
puts result["webhook_secret"] # verify the signed callback
```
Open [Logs](./logs) to inspect status, trace, costs, node output, callback attempts, and the final response.
## Configuration
| Option | Default | Description |
| ---------- | ------------------------------ | ------------------------------- |
| `api_key` | `ENV["FETCH_HIVE_API_KEY"]` | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL |
| `timeout` | `120` | Request timeout in seconds |
```ruby theme={null}
client = FetchHive::Client.new(
api_key: "fhk_...",
base_url: "https://api.fetchhive.com/v1",
timeout: 60
)
```
## Errors
Missing `callback_url` raises `ArgumentError` before a request is sent. Non-2xx responses raise a `RuntimeError` with the status code and body:
```ruby theme={null}
begin
result = client.invoke_hive_agent(
hive_agent: "YOUR_HIVE_AGENT_ID",
objective: "Research competitors and summarize verified findings",
callback_url: "https://example.com/hive-agent-callback"
)
rescue => e
warn "Fetch Hive error: #{e.message}"
end
```
See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for status code meanings.
## Links
* [Gem on RubyGems](https://rubygems.org/gems/fetch_hive)
* [Source on GitHub](https://github.com/Fetch-Hive/ruby-sdk)
## Next steps
* [Invoke from Code](./invoke-from-code) - Overview of starting runs from your app
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Invoke](../api-reference/hive-agents/invoke) - Full endpoint reference
# Running Tasks
Source: https://docs.fetchhive.com/hive-agents/running-tasks
Start Hive Agent runs with objectives, optional sources, live status updates, and reusable blueprints
A Hive Agent run starts from a blueprint and adds the work for one execution: the objective, optional sources, status, trace, costs, nodes, and final result.
## How do I start a run?
Open a Hive Agent in the editor.
Click **Start Run**.
Enter a **Run objective**. This field is required and should describe what this run should accomplish.
Choose a **Search country**. This defaults to **United States** and localizes web search tools for this run (`GPT Search`, `Anthropic Web Search`, `Sonar Web Search`, and **Perplexity Search**). It overrides the Location Country saved on those tools for this execution only.
Review the warning in the dialog. Hive Agents can take minutes or days, and complex runs can become expensive.
Optionally attach **Sources**, then set **Notify me when this run finishes** if you want a completion alert.
Click **Start Run**.
Fetch Hive starts the run, closes the dialog, and opens **Run Console** in the editor so you can watch progress without leaving the page.
## Can I get notified when this run finishes?
In **Start Run**, turn on **Notify me when this run finishes** to override the blueprint default for one execution. The switch starts from the value saved in **Notifications**.
Delivery uses the same **Send via**, **Email address**, and **Telegram account** settings as budget alerts. See [Notifications](./notifications).
## How do I attach sources?
In **Start Run**, open **Sources** and click **Add Source**.
Choose one source type:
| Source type | What it does |
| ----------------------- | --------------------------------------------------------------- |
| **Website** | Scrapes content from one URL and attaches it to the run |
| **File Upload** | Uploads one PDF, Word, text, markdown, CSV, or spreadsheet file |
| **Knowledge Base** | Uses all searchable content from one active Knowledge Base |
| **Knowledge Base Item** | Uses one existing item from a Knowledge Base |
Sources are per-run. They do not become blueprint defaults.
Website and file sources go through source preparation before planning. Fetch Hive processes them into searchable context, records their source-preparation cost, and fails the run before planning if a required source cannot be prepared.
## What does source preparation do?
Source preparation makes run sources available to the planner, executor, and verifier.
For website and file sources, Fetch Hive creates or reuses run-source Knowledge Base records, processes the content, and waits until searchable chunks are ready. For existing Knowledge Bases or Knowledge Base items, Fetch Hive references the selected content without copying the whole source.
The planner receives a compact source manifest. Executor and verifier stages retrieve focused source chunks as they work. Full source bodies are not dumped into the planner prompt.
## What setup is required?
Your workspace must have an active **Default** API key before dashboard Hive Agent runs can start. Fetch Hive uses that key for run attribution and tracing. It does not create a Default key as a side effect of starting a run.
If run start fails with a Default API key error, open [API Keys](../workspace/api-keys) and create or activate a Default key.
## How do I track a running task?
Hive Agent status updates are live. As the run moves through source preparation, planning, execution, verification, retrying, composition, budget checks, and finalization, Fetch Hive updates the run and logs views.
After you start a dashboard run, Fetch Hive opens **Run Console** in the editor so you can follow progress without leaving the page. You can also open **Hive Agents** > **Logs** to inspect the historical run table; selecting a run opens the same console.
In the Run Console, **Pass** means the current execute-and-verify round. **Attempts** are the recorded execute or verify tries for a specific node inside those passes. Compose attempts are tracked separately after node work has been verified.
Use **View technical trace** from the Run Console when you need the detailed request sheet with trace spans, child requests, timings, cost, tokens, inputs, outputs, and metadata. Use the request ID from logs if you need to open the same run from global search.
## Can I rerun the same Hive Agent?
Yes. A Hive Agent is reusable.
Start another run from the same blueprint and enter a new **Run objective**, a different **Search country**, or different sources. Blueprint settings apply to future runs. Existing runs keep the objective, search country, sources, and runtime records they started with.
See also: [Logs](./logs), [Notifications](./notifications), and [Troubleshooting](./troubleshooting).
# Testing and Iteration
Source: https://docs.fetchhive.com/hive-agents/testing-and-iteration
Improve Hive Agent runs by reading verifier feedback, pass outcomes, and completion modes
Iterate on a Hive Agent by running it with a focused objective, reading the rejected nodes and trace details, then tuning stage models, tools, repeat settings, and budget limits.
## How do I read verifier feedback?
Open **Hive Agents** > **Logs** and click a run.
In the run detail sheet, review the node overview and trace stages. Rejected nodes include the reason and required fix from verification. The next execute pass receives that rejection feedback so the executor can try again.
Deterministic checks run before semantic verification. They catch invalid JSON, blank required fields, nested JSON strings, and URL fields that do not resolve. Optional schema fields should be returned as `null` when unused; the platform fills omitted nullable keys before schema validation, but blank required fields still fail verification.
## What should I tune first?
Start with the stage that failed:
* Tune **PLAN** when nodes are poorly decomposed or verification criteria are vague
* Tune **EXECUTE** when outputs are incomplete, unsupported by sources, or missing tool work
* Tune **VERIFY** when good outputs are rejected or weak outputs pass
* Tune **REPEAT** when the run stops too early or spends too long retrying similar failures
For source-heavy tasks, attach better sources before changing models.
## Large multi-document or spreadsheet objectives
When the objective spans a long brief plus an example spreadsheet (or similar multi-file work):
1. On each Knowledge Base item, raise **Maximum chunk length** (about 1500–2000) and set chunking to **Advanced** so overlap applies. Default chunking at 500 characters with no overlap shreds long docs into fragments that are easy to mis-attribute across files.
2. After changing chunk settings, re-run item embedding / source preparation so retrieval uses the new chunks.
3. On the Knowledge Base itself, keep **search score threshold** around **0.1** for hybrid search (the platform default) and keep **search chunk limit** at about **8** (or raise toward 10–20 for multi-file sources). A hybrid threshold of **0.5** is retrieval-hostile for agent-task queries and can return zero chunks even when the vector index is populated.
4. Prefer a stronger **EXECUTE** model or higher reasoning effort for cross-document extraction and citation work.
5. Word the run objective so PLAN creates one node per output sheet or section, and so EXECUTE nodes return structured intermediate rows — not a final formatted spreadsheet. **COMPOSE** owns the spreadsheet-ready assembly.
6. Raise **Max Concurrent Nodes** in Budget Settings when you expect more than about five parallel nodes.
Plan / execute / verify / compose never expose system `file_tools` at invoke time. Grounding comes from platform `SOURCE CONTEXT`, not `read_file`. Downloadable files for spreadsheet or document objectives are produced by the platform after compose.
## How do completion modes affect iteration?
**Strict** mode fails the run when required nodes remain unverified after the max passes.
**Best effort** mode completes with verified work and flags the unverified nodes. Use it when partial verified output is acceptable. When the pass limit is reached with at least one verified node, the run still attempts **COMPOSE** from those verified outputs, then completes with unverified nodes flagged. If no nodes verified, the run completes without a composed final response.
Best effort does not bypass final composition when compose does run: if Compose cannot pass after **Max compose attempts**, the run fails.
## Do edits affect running tasks?
Blueprint edits affect future runs. Stage agent settings can also affect later activity cycles in an already-running task because the runtime reads the current stage agent when an activity starts.
Avoid changing models, tools, or budget settings mid-run unless you intend to change the next stage cycle. For clean comparisons, wait for the run to finish, edit the blueprint, then start a new run with the same objective.
## How do I compare runs?
Use **Hive Agents** > **Logs**.
Compare:
* Objective
* Status
* Pass number
* Node counts
* Source counts
* Total tokens
* Total cost
* Duration
* Final response
* Rejection reasons
Keep test objectives narrow while you tune. Once the loop is reliable, increase scope and budget.
See also: [Running Tasks](./running-tasks) and [Logs](./logs).
# Troubleshooting
Source: https://docs.fetchhive.com/hive-agents/troubleshooting
Fix common Hive Agent setup, source, budget, cancellation, trace, and cost issues
Use this page when a Hive Agent does not start, pauses unexpectedly, fails during source preparation, or produces confusing logs.
## The run says a Default API key is required
Dashboard-started Hive Agent runs require an active workspace **Default** API key.
Open [API Keys](../workspace/api-keys), create or reactivate a key, and mark it as the default key for the workspace. Then start the run again.
## Source preparation failed
Source preparation runs before planning. If a website or file source cannot be processed, the run fails before the planner starts.
Check that:
* Website URLs are reachable
* Uploaded files are supported: PDF, DOC, DOCX, TXT, MD, CSV, XLS, or XLSX
* Knowledge Bases are active
* Knowledge Base items still exist
* File uploads belong to the same workspace
Open the run detail sheet and inspect the source list for the source-specific error.
## The run is blocked
A blocked run usually needs budget approval or has reached a budget gate.
Check **Budget Settings** on the Hive Agent. If the run crossed the **Budget Hint (USD)** with **Conservative** strictness, approve the magic link or decline it. If the run reached the **Budget Cap (USD)**, approve enough additional budget to leave room for execution, verification, and final composition. A run can block during Compose even after all nodes verified.
If the editor control bar shows **Budget stop**, that previous run already ended on budget (`budget_block_state: stopped`). Raise the cap or start a new run with **Start Run** — the stopped run no longer occupies the live-run control.
## The run failed after max passes
The run can stop when it reaches **Max repeat passes** or when final composition fails verification after **Max compose attempts**.
If nodes are verified but Compose failed, open the final response section and read the compose issue. The verified node outputs are still available as supporting detail, but the final composed response did not pass the assembly check.
On the Compose card in the run console, click **Retry compose** to re-run only the compose stage. You can raise the budget cap with an optional additional budget amount before confirming. Compose retry keeps verified node outputs and does not re-run plan, execute, or verify.
Open the run detail sheet and read the verifier rejection reasons. Then tune the stage that caused the failure:
* Improve sources or **PLAN** if nodes are unclear
* Add tools or change **EXECUTE** if the agent cannot produce the required output
* Adjust **VERIFY** if the verifier is too strict or too loose
* Adjust **COMPOSE** if verified node outputs are correct but the final response omits, distorts, or formats them poorly
* Use **Best effort** if partial verified node output is acceptable — after max passes it will still try Compose from verified nodes when at least one node verified
* If verifier rejections keep citing mismatched Source `[N]` numbers across multi-file sources, raise Knowledge Base item chunk length, switch to Advanced chunking, re-embed, and prefer a stronger EXECUTE model (see [Testing and Iteration](./testing-and-iteration#large-source-objectives))
* A completed best-effort run can still show a Max passes message in the detail view while `status` is `completed` — check status and whether a final response / composition was stored, not only the error text
## Nodes keep failing with missing evidence / UNVERIFIED placeholders
If execute outputs admit they never opened the brief/spreadsheet, or alternating passes bounce between `check_failed:required_nonblank` and `unsupported_source_claim` / `missing_required_evidence`, the executor likely received **no SOURCE CONTEXT**.
Check in order:
1. Knowledge Base **search score threshold** — platform default is about **0.1** for hybrid search. A threshold of **0.5** is retrieval-hostile for long multi-document agent queries and can return zero chunks even when embeddings exist.
2. Knowledge Base **search chunk limit** — platform default is **8**; raise toward 10–20 for multi-file sources.
3. Item chunking — Advanced + \~1500 max length, then re-embed and confirm item `run_status` is completed.
4. On the execute attempt payload, inspect `source_chunks` and `source_retrieval`:
* Empty `source_chunks` with ready sources means retrieval failed after the platform degrade ladder.
* `source_retrieval.stages` shows clamped-threshold → floor-threshold → raw-document-fallback attempts, plus per-request HTTP success/errors.
Plan / execute / verify / compose do not receive system `file_tools`; grounding is `SOURCE CONTEXT` only. Downloadable Hive Agent files are produced by the platform after compose and appear on the run alongside the text final response.
After a platform deploy, retrieval that exhausts the degrade ladder with zero chunks (`empty_reason: all_stages_empty`) fails the run immediately with `source_retrieval_empty` instead of burning the full pass budget. Missing API keys / blank queries (`no_requests`) still soft-degrade and continue without SOURCE CONTEXT.
## The run failed with provider\_account\_error
Provider billing/quota errors (for example Anthropic `credit balance is too low`) stop the Hive Agent run instead of consuming remaining execute/verify passes. Top up the provider account / workspace BYOK integration, then start a new run.
## The run was cancelled
Hard-stop cancellation stops the run quickly and marks remaining node work cancelled.
Partial-result cancellation stops new work, lets already-started work finish, and keeps verified node output in the run detail sheet. If cancellation happens during Compose, the in-flight compose attempt may finish, but no further compose attempts are scheduled. The terminal status is still `cancelled`.
If a run still looks live in logs after the platform has already stopped it, **Cancel run** still marks the Fetch Hive run cancelled. You do not need an active backend execution for cleanup.
You can also cancel stuck runs for archived Hive Agents from Hive Agent logs. Archived blueprints cannot start new runs.
## Trace details look delayed or incomplete
Child AgentRun traces can arrive after their parent Hive Agent stage. Refresh the detail sheet after the child run finishes.
Use the request ID from the log row or stage detail to open the run directly from global search.
If a budget gate or step-cost bar looks far longer than its parent Execute / Verify row, refresh after the run finishes. Budget markers are zero-duration points on the stage timeline; a background sync after the stage completes moves them onto the correct anchor.
## The run cost is higher than expected
Check:
* **Max Concurrent Nodes**
* **Max repeat passes**
* **Max compose attempts**
* Source preparation costs
* Number of planned nodes
* Executor and verifier models
* Tool calls made by executor nodes
* Whether rejected nodes repeated through multiple passes
* Whether the final response needed multiple compose attempts
Lower concurrency, use a tighter objective, attach fewer sources, set a lower **Budget Cap (USD)**, or use **Conservative** strictness when you want the run to pause earlier.
See also: [Budget Approval](./budget-approval) and [Logs](./logs).
# Cost Tracking
Source: https://docs.fetchhive.com/live-chat/cost-tracking
How Live Chat messages are billed for signed-in accounts, and how guest chat usage is limited under fair use
Live Chat usage is billed differently depending on whether you are signed in or using the guest (logged-out) experience.
## Signed-in accounts
When you are logged in, each message run is charged to your Fetch Hive account under the **selected workspace**. Billing follows the same hosted vs personal rules as the rest of Fetch Hive.
### Task credits
Every Live Chat turn that runs a model or agent records **platform task credits** (for example, 1 task for a standard AI model or agent call). Tool calls that complete during the turn can add their own task costs.
See [Task costs](../resources/task-costs) for the full service table.
### Hosted models (LLM wallet)
If the model or agent uses **Hosted** charge type, Fetch Hive pays the provider
on your behalf. In addition to task credits, the recorded provider cost is
passed through to your account's **hosted LLM wallet** with no per-call markup.
Wallet-credit purchases have a separately disclosed, non-refundable service fee
(currently 6%, with an \$0.80 minimum).
If the wallet is empty, the run fails with insufficient hosted LLM credits until you add credits or switch to a personal key where supported.
### Personal API keys
If the model or agent uses **Personal** charge type with a connected provider key:
* The **provider bills your API key** directly for model usage.
* Fetch Hive still records the usual **platform task credits**.
* Hosted LLM wallet balance is **not** used for that model usage.
Connect provider credentials under workspace [Integrations](../workspace/integrations). See [Use your own API Key](../workspace/llm-providers) for charge-type setup.
### Where to review usage
* Workspace **Billing** and **Analytics** in the Fetch Hive dashboard
* **Logs** for agents (and related run detail) under the workspace that ran the chat — see [Agent logs](../agents/logs) and [Credit Usage](../monitoring/credit-usage)
## Guest chat
Live Chat also offers a **guest** experience so people can try the product without signing up. Guest chat is intentionally limited and covered by Fetch Hive’s [fair usage policy](./fair-usage).
Guests can expect:
| Limit | What it means |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Limited tools** | Most tools are shown for discovery but require sign-in to use. Only a small set of guest-allowed tools can run while logged out. |
| **Limited models** | Guest mode allows GPT 5.4 Nano only — other hosted models and saved agents require sign-in. |
| **Limited usage** | Daily caps apply per session, device, and IP. Hitting a cap prompts you to create an account to continue. |
| **Ephemeral chats** | Guest conversations are not saved to an account. Starting a new chat discards the prior thread on the client. |
| **No attachments / gated features** | Uploads and other signed-in features require an account. |
Guest usage is funded by Fetch Hive (not your personal wallet). Fair usage caps exist so demo traffic stays available for everyone. Abuse, automated scraping, or sustained high-volume guest use may be rate-limited or temporarily disabled; Fetch Hive may turn guest chat off at any time. When guest chat is unavailable, the app asks you to sign up. Full rules: [Fair usage policy](./fair-usage).
Create a free account to save conversations, unlock the full model and tool set, and use your own workspace credits / personal API keys.
## Related
* [Live Chat overview](./overview)
* [Workspaces](./workspaces)
* [Available tools](./tools)
* [Fair usage policy](./fair-usage)
* [Task costs](../resources/task-costs)
* [Billing](../workspace/billing)
* [Use your own API Key](../workspace/llm-providers)
# Fair Usage Policy
Source: https://docs.fetchhive.com/live-chat/fair-usage
Fair use rules for Fetch Hive Live Chat, including guest (logged-out) trial access
This Fair Usage Policy explains how Fetch Hive expects people to use [Live Chat](https://chat.fetchhive.com) — both **signed-in** workspace chat and the **guest** (try-before-signup) experience. Limits exist so the service stays available and useful for everyone.
By using Live Chat or guest chat, you agree to this policy. It sits alongside Fetch Hive’s other product terms and [Cost tracking](./cost-tracking).
## Purpose
We provide Live Chat so you can talk with hosted models, saved agents, and tools in your workspace. Guest chat is a limited, complimentary trial so people can evaluate the product without creating an account. Fair usage rules protect service quality, prevent abuse, and keep trial capacity available for new users.
## Scope
This policy applies to:
* **Signed-in Live Chat** on [chat.fetchhive.com](https://chat.fetchhive.com) (workspace models, agents, tools, and saved conversations)
* **Guest chat** when guest mode is enabled (logged-out trial)
* Related rate limits, safety controls, and availability of those surfaces
Billing and credit details for signed-in accounts are covered in [Cost tracking](./cost-tracking). Guest chat is funded by Fetch Hive and is **not** a substitute for a paid or credited workspace.
## Allowed use
You may use Live Chat for interactive, human-driven conversation that is lawful and consistent with the product’s purpose — for example evaluating models, chatting with your workspace agents, and using tools you are authorized to use.
Guest chat is for **evaluation and trial** only: send a limited number of messages, explore the UI, and decide whether to sign up. It is not intended as ongoing free production capacity.
## Guest chat allowances
Guest mode is intentionally limited. Typical limits include (exact values may change):
| Area | Expectation |
| ---------------- | ---------------------------------------------------------------------------------------------------- |
| **Models** | A small allowlist only (for example GPT 5.4 Nano) — not the full hosted catalog or your saved agents |
| **Tools** | Most tools require sign-in; only guest-allowed tools can run while logged out |
| **Volume** | Daily caps per session, device signal, and IP; per-thread message and length caps |
| **Features** | No attachments and other gated features; conversations are ephemeral and not saved to an account |
| **Availability** | Guest chat may be rate-limited, paused, or turned off at any time |
When you hit a limit, Live Chat will usually ask you to create an account to continue. See [Cost tracking — Guest chat](./cost-tracking#guest-chat) for a product-facing summary.
## Prohibited use
You must not:
* Use Live Chat or guest chat for illegal, fraudulent, harassing, or harmful activity
* Attempt to overload, disrupt, or interfere with the service or other users
* Bypass or circumvent rate limits, safety controls, session cookies, fingerprinting, or kill switches
* Use bots, scripts, scrapers, or other automation to send messages, mint sessions, farm quotas, or extract outputs at scale
* Create multiple identities, rotate IPs/devices, or otherwise evade guest or account limits
* Use guest chat as a free production backend, bulk processing pipeline, or substitute for a signed-in workspace
* Resell, white-label, or commercially redistribute guest access or complimentary capacity
* Probe, reverse engineer, or attack the service, models, or infrastructure beyond normal interactive use
* Infringe others’ intellectual property or privacy rights through your prompts or use of outputs
## Commercial and competitive misuse
Guest and complimentary capacity are for evaluation. Do not use them to power a commercial product, compete with Fetch Hive, or systematically harvest model behavior or outputs. Signed-in Live Chat must stay within your plan, credits, and workspace authorization.
## AI outputs
Model and agent responses can be wrong, incomplete, or outdated. Verify important information yourself. Live Chat is not a substitute for professional advice. You are responsible for how you use outputs.
## Monitoring and enforcement
We may monitor usage patterns (including volume, automation signals, and abuse indicators) to enforce this policy and protect the service.
If we believe your use violates this policy, risks the service, or creates legal or security exposure, we may take action including:
* Throttling or rate-limiting requests
* Requiring sign-up or additional verification
* Restricting tools, models, or features
* Suspending or terminating guest or account access
## Right to disable guest chat
**Fetch Hive may enable, restrict, suspend, or permanently disable guest chat (and related complimentary trial access) at any time, for any reason or no reason, with or without notice.** That includes turning guest mode off globally, for regions or IP ranges, or for specific sessions when we detect abuse, capacity pressure, or operational need.
When guest chat is unavailable, the app may show a sign-up or log-in wall. Signed-in Live Chat remains subject to your account status, credits, and this policy.
## No guarantee of availability
Live Chat and guest chat are provided **as available**. We do not guarantee uptime, latency, capacity, or that any particular model, tool, or guest allowance will remain offered. Limits, features, and this policy may change. Continued use after a change means you accept the current version.
## Related
* [Cost tracking](./cost-tracking) — how signed-in billing works and guest fair-use summary
* [Live Chat overview](./overview)
* [Workspaces](./workspaces)
* [Available tools](./tools)
* [Task costs](../resources/task-costs)
* [Billing](../workspace/billing)
# Overview
Source: https://docs.fetchhive.com/live-chat/overview
Use Fetch Hive Live Chat at chat.fetchhive.com to talk with hosted models, saved agents, and tools
[Live Chat](https://chat.fetchhive.com) is Fetch Hive's full chat product — the same surface as a consumer AI chat app, wired to your workspace models, saved agents, tools, and conversation history.
This is **not** the agent editor's test panel. The editor panel is for throwaway agent dry-runs inside the dashboard. Live Chat is a separate app where conversations persist and you can switch models, attach files, and use tools.
For editor-only testing, see [Testing with Chat](../agents/testing-with-chat).
## What you can do
* Chat with **hosted models** from OpenAI, Anthropic, Google, xAI, and Perplexity (subject to workspace access, plan, and credits).
* Open a **saved agent** from your workspace and keep using that agent's configured model, prompt, and tools.
* **Save chats** in your account — rename, favorite, and search recent conversations from the sidebar.
* Attach files from the composer (**Upload photos & files**) — images, audio, PDF, DOCX, and other supported documents. Images require a vision-capable model; audio is transcribed before send.
* Enable **tools** on direct-model chats (search, image generation, connected integrations). See [Available tools](./tools).
* Answer **clarifying questions** when an agent needs to disambiguate your request — choose from short options (or type your own) in a card, then the agent continues. Your answer is not shown as a separate chat bubble.
* Start a **new chat** anytime; guest (logged-out) sessions are ephemeral until you sign up.
### Developer plan models
On the free **Developer** plan, Live Chat unlocks a smaller hosted set: GPT 5.4 Nano and Mini, Gemini 2.0 Flash and Flash Lite, Gemini 2.5 Flash and Flash Lite, and Claude Haiku 4.5. Other models (and Saved Agents configured on those models) stay visible in the picker with an **Upgrade plan** action that opens billing plans. Paid plans unlock the full hosted catalog.
## Open Live Chat
Go to [chat.fetchhive.com](https://chat.fetchhive.com) and sign in with your Fetch Hive account (or try guest mode when it is enabled for your environment).
Pick a **model** or a **saved agent** from the target picker above the composer, then send a message.
## Models vs saved agents
| Mode | What it uses | Persistence | Tools |
| ------------ | ------------------------------------------- | ---------------------------------- | -------------------------------------------------------- |
| Direct model | The hosted model you select in the picker | Conversation saved to your account | You choose tools from the composer **+** menu (up to 10) |
| Saved agent | The agent config you built in the dashboard | Conversation saved to your account | Agent's preset tools (not edited mid-chat in Live Chat) |
After a saved-agent conversation has started, switch to a different agent or model with **New Chat**. Direct-model chats can change model (and reasoning) while idle.
## How this differs from the agent editor Chat panel
| | Live Chat (`chat.fetchhive.com`) | Agent editor Chat |
| -------------- | ---------------------------------------------------------- | --------------------------------------- |
| Purpose | Day-to-day product chat | Test a single agent before API/SDK use |
| Messages saved | Yes (when signed in) | No |
| Models | Full hosted catalog + saved agents | Fixed to the open agent's saved config |
| Tools | Selectable on direct models; agent presets on saved agents | Agent's configured tools only |
| App | Separate chat SPA | Panel inside the dashboard agent editor |
## Related
* [Workspaces](./workspaces) — switch workspaces; agents, chats, and logs stay scoped to the selection
* [Cost tracking](./cost-tracking) — task credits, hosted LLM wallet vs personal keys, and guest fair use
* [Fair usage policy](./fair-usage) — guest trial limits, abuse rules, and our right to disable guest chat
* [Available tools](./tools) — tools you can use in Live Chat (with links to MCP tool docs)
* [Creating and Configuring](../agents/creating-and-configuring) — build saved agents in the dashboard
* [MCP Tools overview](../agents/mcp-tools/overview) — deep dives for each agent/tool integration
* [Fetch Chat Direct-Model Tools](../agents/fetch-chat-direct-model-tools) — composer tool selection behavior
# Available tools
Source: https://docs.fetchhive.com/live-chat/tools
Tools available in Fetch Hive Live Chat, with links to detailed MCP tool docs
In [Live Chat](https://chat.fetchhive.com), **direct-model** conversations can enable tools from the composer **+** menu. Selected tools are stored on the conversation server-side; the browser does not send tool config on each invoke.
**Saved agents** keep the tool set you configured in the dashboard — you do not pick tools mid-chat for those conversations.
For how selection works in the UI, see [Fetch Chat Direct-Model Tools](../agents/fetch-chat-direct-model-tools). For full setup and behavior of each integration, use the linked pages under [MCP Tools](../agents/mcp-tools/overview).
## Native search and generation
These tools do not require a separate OAuth connection. Availability still depends on the selected model's provider.
| Tool | What it does | Docs |
| -------------------- | ------------------------------------------------ | ---------------------------------------------------------------- |
| GPT Search | Web search powered by GPT (OpenAI models) | [GPT Search](../agents/mcp-tools/gpt-search) |
| Anthropic Web Search | Live web search for Claude models | [Anthropic Web Search](../agents/mcp-tools/anthropic-web-search) |
| xAI Web Search | Real-time web search for Grok | [xAI Web Search](../agents/mcp-tools/xai-search) |
| X Search | Search posts on X/Twitter with Grok | [X Search](../agents/mcp-tools/x-search) |
| Sonar Web Search | Built-in search for Perplexity Sonar models | [Sonar Web Search](../agents/mcp-tools/perplexity-search) |
| Perplexity Search | Standalone Search API across supported providers | [Perplexity Search](../agents/mcp-tools/perplexity-search-api) |
| Google Grounding | Ground Gemini responses with Google Search | [Google Grounding](../agents/mcp-tools/google-grounding) |
| Create an image | Generate images from text prompts | [Image Generation](../agents/mcp-tools/image-generation) |
## Connected integrations
Connect the account once under workspace **Integrations**, then select the tool in Live Chat. Connection is required before the tool can run.
| Tool | What it does | Docs |
| --------------- | ----------------------------------------- | ------------------------------------------------------ |
| Linear | Create and manage Linear issues | [Linear](../agents/mcp-tools/linear) |
| Airtable | Read and write Airtable records | [Airtable](../agents/mcp-tools/airtable) |
| Gmail | Send, read, and search email | [Gmail](../agents/mcp-tools/gmail) |
| Google Drive | Upload, download, and manage Drive files | [Google Drive](../agents/mcp-tools/googledrive) |
| Google Calendar | Create and manage calendar events | [Google Calendar](../agents/mcp-tools/googlecalendar) |
| HubSpot | Manage CRM contacts, companies, and deals | [HubSpot](../agents/mcp-tools/hubspot) |
| Notion | Work with Notion pages and databases | See [MCP Tools overview](../agents/mcp-tools/overview) |
| Dropbox | Manage files in Dropbox | See [MCP Tools overview](../agents/mcp-tools/overview) |
Additional Composio and workspace MCP integrations may appear in your catalog when connected. The Live Chat picker lists what your workspace exposes for Fetch Chat.
## Limits
* Up to **10** tools per direct-model conversation.
* Tool changes are blocked while a response is streaming.
* Guest (logged-out) Live Chat shows tools for discovery but requires sign-in to use them.
* Live Chat applies lean search defaults (low context size; Anthropic web search max uses 1) and localizes results by request IP when available. Saved Agents keep the defaults configured in the agent editor.
## Related
* [Live Chat overview](./overview)
* [Workspaces](./workspaces)
* [Cost tracking](./cost-tracking)
* [Fair usage policy](./fair-usage)
* [MCP Tools overview](../agents/mcp-tools/overview)
* [Workspace integrations](../workspace/integrations) (when available in your docs locale)
# Workspaces
Source: https://docs.fetchhive.com/live-chat/workspaces
Switch workspaces in Live Chat, and understand how agents, chats, and logs stay scoped to the selected workspace
Live Chat is always tied to one **workspace** at a time. The workspace you select controls which saved agents you can open, where new conversations are stored, and which dashboard logs those runs appear under.
## Switch workspace
1. Open [Live Chat](https://chat.fetchhive.com) and sign in.
2. Open your **account menu** (avatar / name in the sidebar or header).
3. Open the workspace submenu — it shows the name of your current workspace.
4. Choose another workspace from the list.
After you switch, the agent and model pickers, recent chats, and new conversations all follow the newly selected workspace.
## What stays scoped to the selected workspace
| Area | Behavior |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Saved agents** | You only see agents that belong to the selected workspace. Agents from other workspaces do not appear in the picker. |
| **Conversations** | New chats are saved against the selected workspace. Recent chats and search results follow that workspace. |
| **Logs** | Runs from Live Chat (direct models and saved agents) are recorded under the selected workspace. Open that workspace in the Fetch Hive dashboard to review logs, usage, and traces. |
| **Integrations / tools** | Connected tools and workspace MCP servers come from the selected workspace's Integrations setup. |
Switching workspace does not move existing chats between workspaces. To continue a conversation that was started in another workspace, switch back to that workspace first.
## Tips
* If a saved agent is missing from the picker, confirm you are in the workspace where that agent was created in the dashboard.
* Use **New Chat** after switching if you still have a target from a previous workspace open.
* Manage agents, integrations, and billing for a workspace from the Fetch Hive dashboard — Live Chat uses the same workspace membership and permissions.
## Related
* [Live Chat overview](./overview)
* [Cost tracking](./cost-tracking)
* [Fair usage policy](./fair-usage)
* [Creating and Configuring](../agents/creating-and-configuring)
* [Agent logs](../agents/logs)
* [Workspace overview](../workspace/overview)
# Creating and Editing
Source: https://docs.fetchhive.com/prompts/creating-and-editing
Create a prompt, add messages, manage inputs, and test it in the prompt editor
Use the prompt editor to write a standalone prompt, pass test inputs, and check the response before you create a prompt deployment.
## Overview
You start in the **Prompts** list, create a prompt, and open the editor. From there, you can add messages, work with prompt inputs, adjust editor settings, and click **Run** to test the prompt inside the dashboard.
The in-editor **Run** action is for testing. It is separate from calling a prompt through the public API.
## How do I create a prompt?
Open **Prompts** in the sidebar.
Click **Create Prompt**.
Enter a name for the prompt. If your workspace uses categories, you can also choose a category before you save.
Click **Create Prompt** again to open the prompt editor.
## How do I add and edit prompt messages?
Open the prompt in the editor.
In the prompt configuration area, click **Add Message**.
Choose the message content you want the model to receive. Keep the instructions short and direct when you're testing a new prompt.
Edit existing messages in the same prompt area until the prompt behaves the way you want.
If you want the prompt to accept dynamic values, add variables in your message content using the same variable format used elsewhere in the editor, such as `{{text}}`.
For vision-capable models, `user` messages can also include an image URL. Click the image icon on the message and paste a public image URL.
## How do I work with inputs?
When your messages include variables, click **Inputs** in the editor header.
Use the input values sheet to enter test values for each variable used by the prompt.
Update the values any time you want to test a different input without changing the prompt messages themselves.
These input values are for editor testing. They help you run the prompt with realistic sample data before you create a prompt deployment.
## How do I test a prompt in the editor?
After you add your messages and any input values, click **Run**.
Fetch Hive sends the current prompt configuration to the model and shows the result in the response area of the editor.
Use this step to check the output before you save a version or create a prompt deployment. If the result is not what you want, update the messages or inputs and run it again.
## What else can I configure in the prompt editor?
The prompt editor includes additional configuration areas beyond the message list. Depending on the prompt and provider, you may see model settings, response format controls, tools, evaluations, and other editor options.
If a saved prompt uses a retired model, the editor shows a model warning and test runs are blocked with `model_deprecated`. Choose a current model before running or publishing the prompt again.
For Anthropic Claude models, the model parameters include **Prompt Cache**. Leave it **Disabled** for normal one-off runs, choose **5 minutes** for repeated runs that reuse the same prompt context in a short window, or choose **1 hour** when follow-up calls may happen after a longer pause. Fetch Hive applies this as Anthropic prompt caching on stable prompt prefixes only.
Use these controls when you need to refine how the prompt runs in the editor.
See also: [Publishing and Versioning](./publishing-and-versioning) and [Run with API](./run-with-api)
# Logs
Source: https://docs.fetchhive.com/prompts/logs
Review prompt activity logs, inspect request details, and check inputs and responses for individual runs
Prompt logs help you inspect how a prompt ran after you tested it or invoked it through runtime paths. Use the logs view to review individual runs, inspect request details, and check the inputs and response for a selected completion.
## Accessing activity logs
Open the prompt in the editor.
Click **Activity Logs** in the header.
Fetch Hive opens the prompt-specific activity log view for that prompt.
The logs page includes a paginated table of runs on the left and a detail panel for the selected run on the right.
You can also use **Refresh logs** to reload the table or **Editor** to go back to the prompt editor.
## What's tracked
The log table shows summary data for each run, including:
* Owner
* Completed time
* Provider
* Model
* Charge type
* Status
* Provider charge
* Total tokens
* Duration
When you select a run, the detail panel gives you additional views:
* **Response** for the generated output
* **Request** for model settings and usage details
* **Inputs** for the values passed into the prompt
* **User metadata** for caller-defined audit fields sent as `user_metadata`
For Claude runs, the **Request** panel can also show **Prompt Cache**, which is the configured Anthropic prompt-cache TTL assigned to that request. Cached read and write token counts remain in the existing token usage breakdowns.
For models that emit visible thinking or reasoning content, the **Response** view shows it in a collapsible thinking section above the assistant output.
If the selected run failed, the detail panel shows the error message. Some providers can also add provider-specific metadata. For example, Perplexity runs include a citations view. Perplexity Sonar Deep Research logs can also show separate citation tokens, reasoning tokens, and search query counts when the provider returns those usage fields.
## Traces
The prompt activity log view focuses on run details such as **Response**, **Request**, and **Inputs**.
Start with **Response**, then check **Request** and **Inputs** to understand how the prompt ran.
## Filtering and search
The prompt activity log view includes pagination, row selection, and **Refresh logs**.
Use **User metadata** to filter by a tracked metadata property. Choose a property key to find runs where that key exists, or add an exact value to match scalar values such as `cus_123`, `enterprise`, `true`, or `12`.
Fetch Hive tracks metadata property names over time from prompt invokes so the filter can suggest keys your workspace has actually sent. Old logs without `user_metadata` remain visible normally, but they are excluded when a user metadata filter is active. See [Invoke metadata](../user-tracking/invoke-metadata) for request examples.
## Notes
* The log detail view includes a share link action for the selected run.
* A selected run can also include a discussion thread so your team can comment on the run in context.
* Use the prompt editor for iteration and the logs view for after-the-fact inspection.
See also: [Creating and Editing](./creating-and-editing) and [Run with API](./run-with-api)
# Overview
Source: https://docs.fetchhive.com/prompts/overview
Create standalone prompts, test them in the editor, version changes, and run them through prompt deployments
Use prompts when you want to write and test a single LLM interaction without building a full workflow. In this section, you'll create prompts, work with inputs, save versions, create prompt deployments, and review prompt activity.
Standalone prompts are different from prompt steps inside workflows. These pages cover the prompt editor under **Prompts**, not the workflow builder under **Workflows**.
## What you'll find here
* [Creating and Editing](./creating-and-editing) - Create a prompt, add messages, work with inputs, and test it in the editor
* [Publishing and Versioning](./publishing-and-versioning) - Save versions, review version history, roll back changes, and create prompt deployments
* [Run with API](./run-with-api) - Invoke a prompt deployment with cURL using the public API
* [Logs](./logs) - Review prompt runs, request details, inputs, and related activity
* [Run with Python SDK](./run-with-python-sdk) - Invoke a prompt deployment from Python with `fetch-hive-sdk`
* [Run with Node.js SDK](./run-with-nodejs-sdk) - Invoke a prompt deployment from Node.js with `@fetch-hive/sdk`
* [Run with Ruby SDK](./run-with-ruby-sdk) - Invoke a prompt deployment from Ruby with the `fetch_hive` gem
* [Run with PHP SDK](./run-with-php-sdk) - Invoke a prompt deployment from PHP with `fetch-hive/sdk`
# Publishing and Versioning
Source: https://docs.fetchhive.com/prompts/publishing-and-versioning
Save prompt versions, review version history, roll back changes, and create prompt deployments for runtime use
Use versioning to save stable checkpoints of a prompt and create a prompt deployment when you want to call that prompt outside the editor.
## Overview
The prompt editor separates authoring from runtime use. You can test changes with **Run**, save them with **Save Version**, review older versions in **Version History**, and use **Create Endpoint** or **Update Endpoint** when you're ready to make the prompt available outside the editor as a prompt deployment.
In docs prose, refer to this public runtime surface as a prompt deployment. Keep UI labels such as **Create Endpoint** and **Update Endpoint** exactly as they appear in the product.
## How do I save a prompt version?
Open the prompt in the editor.
Click **Save Version** in the header.
Enter a short description of what changed.
Click **Save Version** to create a named checkpoint for the current state of the prompt.
Use version descriptions that explain the change clearly. This makes it easier to review and roll back later.
## How do I review version history?
Open the prompt in the editor.
Click **Version History** in the header.
Select a version from the list to inspect its saved snapshot and description.
Use this view when you need to compare recent changes, confirm who saved a version, or decide which version you want to restore.
## How do I roll back to an earlier version?
Open **Version History**.
Select the version you want to restore.
Click **Rollback**.
Confirm the rollback in the confirmation dialog.
After the rollback completes, Fetch Hive restores the selected version in the prompt editor so you can review it and continue working from that point.
## How do I create or update a prompt deployment?
Open the prompt in the editor.
Open the prompt menu in the header, then click **Create Endpoint** if you do not have one yet.
Enter the name, then save it. Fetch Hive takes you to the deployment view for the new prompt deployment and its initial variant.
If the prompt already has a prompt deployment, open the same menu and click **Update Endpoint**. From there, you can create a new variant or update an existing variant.
Use the deployment name and variant when you want to invoke the prompt through the public API.
Prompt deployments keep the prompt's Claude **Prompt Cache** setting when a version is created or updated. You can also configure the deployment fallback model's Claude prompt-cache TTL separately in the deployment settings.
If the deployed variant or enabled fallback model uses a retired model, invocation is blocked with `model_deprecated`. Update the deployment variant or fallback settings to an active model before calling it again.
## Deployment and versioning notes
Prompt versions and deployment variants are related, but they are not the same thing. A prompt version is your editor checkpoint. A deployment variant is part of the runtime surface you use when you invoke the prompt outside the editor.
Keep using **Run** while you are iterating inside the editor. Create or update a prompt deployment when you need a callable runtime entrypoint for your app or integration.
See also: [Creating and Editing](./creating-and-editing) and [Run with API](./run-with-api)
# Run with API
Source: https://docs.fetchhive.com/prompts/run-with-api
Invoke a prompt deployment with the public API using your API key, deployment name, and variant
Use the public invoke endpoint when you want to call a prompt from your own app or service. First create a prompt deployment and variant in the dashboard, then invoke the deployment with your workspace API key.
## Authentication
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
See [API Keys](../workspace/api-keys) for how to create and manage keys.
## Endpoint
`POST https://api.fetchhive.com/v1/prompt/invoke`
Before you call this endpoint, create or update a prompt deployment from the prompt editor. See [Publishing and Versioning](./publishing-and-versioning) for the UI flow.
## Request
Use this request shape:
| Field | Type | Required | Description |
| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------- |
| `deployment` | string | Yes | The prompt deployment name you created for the prompt |
| `variant` | string | Yes | The prompt deployment variant you want to run |
| `inputs` | object | No | Key-value pairs for any prompt variables used by the prompt |
| `streaming` | boolean | No | Whether the response should be streamed |
| `metadata` | object | No | Flat caller-defined metadata for audit and log filtering. This is not used as prompt input. |
`metadata` must be flat and scalar-only: strings, numbers, booleans, or `null`. Nested objects and arrays return a validation error before the run starts.
This endpoint does not accept top-level `image_urls` or document
`attachments`. If a deployed prompt uses an image URL message part, configure
that image URL in the prompt editor or bind it through an `inputs` variable in
the prompt content. For runtime image/document attachments, invoke an agent
with [`POST /v1/agent/invoke`](../api-reference/agents/invoke).
## Basic example
```bash theme={null}
curl 'https://api.fetchhive.com/v1/prompt/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
"deployment": "YOUR_DEPLOYMENT_NAME",
"variant": "YOUR_VARIANT_NAME",
"inputs": {
"text": "Fetch Hive helps teams ship AI products faster."
},
"metadata": {
"customer_id": "cus_123",
"plan": "enterprise"
},
"streaming": true
}' \
--compressed
```
Replace `YOUR_API_KEY`, `YOUR_DEPLOYMENT_NAME`, `YOUR_VARIANT_NAME`, and the `inputs` object with your real values.
Use `metadata` for audit fields you want to see or filter in logs, such as customer IDs, plan names, regions, or experiment names. Do not put prompt variables there; prompt variables belong in `inputs`. See [Invoke metadata](../user-tracking/invoke-metadata) for examples and log filtering details.
## Response
If `streaming` is `true`, the API returns a stream of `data:` events rather than one final JSON object. If the provider fails after the stream has opened, the API sends a final `error` event before closing the stream.
### Streaming response
You can receive different event types during the stream. For example:
Reasoning or thinking event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "reasoning",
"model": "gpt-5-nano",
"response": " seems"
}
```
Response event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "response",
"model": "gpt-5-nano",
"response": " too"
}
```
Final usage event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "usage",
"usage": {
"duration": 4.79230260848999,
"prompt_tokens": {
"total_tokens": 24,
"cached_tokens": 0,
"cached_read_tokens": 0,
"cache_write_tokens": 0
},
"completion_tokens": {
"total_tokens": 170,
"reasoning_tokens": 64
},
"total_tokens": 194
},
"stop_reason": "completed"
}
```
Error event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "error",
"error": "cohere provider stream error: HTTP 400: invalid request",
"message": "cohere provider stream error: HTTP 400: invalid request",
"provider": "cohere",
"error_type": "provider_stream_error",
"status_code": 502
}
```
### Non-streaming response
If `streaming` is `false`, the API returns a single JSON response. Provider execution failures return `502 Bad Gateway` with an `error` message. For example:
```json theme={null}
{
"request_id": "req_019d528660dd7e22b15e5b13a1931c50",
"model": "gpt-5-nano-2025-08-07",
"duration": 4.641960144042969,
"reasoning": "**Clarifying summary request**\n\nI need to follow up on the user's request for a 50-word summary since their message was incomplete. I should ask them to clarify the text or topic they'd like summarized. I can suggest options like pasting a passage or specifying a source. I’ll also mention I can summarize up to 50 words or suggest a different length if they prefer. Let’s get that response ready!",
"response": "I’m missing the text or topic to summarize. Please paste the passage (or name the work) you want summarized, and I’ll provide exactly 50 words. If you prefer a different length, tell me the target word count. I can summarize articles, chapters, speeches, or any provided content.",
"usage": {
"prompt_tokens": {
"total_tokens": 24,
"cached_tokens": 0,
"cached_read_tokens": 0,
"cache_write_tokens": 0
},
"completion_tokens": {
"total_tokens": 187,
"reasoning_tokens": 64
},
"total_tokens": 211
},
"stop_reason": "completed"
}
```
## Next steps
* [Publishing and Versioning](./publishing-and-versioning)
* [Run with Python SDK](./run-with-python-sdk) - Invoke a prompt from Python
* [Run with Node.js SDK](./run-with-nodejs-sdk) - Invoke a prompt from Node.js
* [Run with Ruby SDK](./run-with-ruby-sdk) - Invoke a prompt from Ruby
* [Run with PHP SDK](./run-with-php-sdk) - Invoke a prompt from PHP
# Run with Node.js SDK
Source: https://docs.fetchhive.com/prompts/run-with-nodejs-sdk
Invoke a prompt deployment from Node.js or TypeScript with the @fetch-hive/sdk package
Use the official `@fetch-hive/sdk` package when you want to invoke a prompt deployment from Node.js or TypeScript. The SDK wraps the public [`POST /v1/prompt/invoke`](../api-reference/prompts/invoke) endpoint with a typed client, handles authentication, and exposes streaming as an `AsyncIterable`.
## Installation
```bash theme={null}
npm install @fetch-hive/sdk
# or
yarn add @fetch-hive/sdk
# or
pnpm add @fetch-hive/sdk
```
The SDK targets Node.js 18+ (it uses the global `fetch`) and ships with TypeScript types out of the box.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key:
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```typescript theme={null}
import { FetchHive } from '@fetch-hive/sdk';
const client = new FetchHive();
```
Or pass the key explicitly:
```typescript theme={null}
const client = new FetchHive({ apiKey: 'fhk_...' });
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Invoke a prompt deployment and read the final response:
```typescript theme={null}
import { FetchHive } from '@fetch-hive/sdk';
const client = new FetchHive();
const result = await client.invokePrompt({
deployment: 'YOUR_DEPLOYMENT_NAME',
variant: 'YOUR_VARIANT_NAME',
inputs: { text: 'Fetch Hive helps teams ship AI products faster.' },
});
console.log(result.response);
```
`invokePrompt` returns a `Promise` that resolves to the parsed JSON body once the prompt has completed. See the [non-streaming response shape](../api-reference/prompts/invoke#response).
## Method reference
| Field | Type | Required | Description |
| ------------ | ----------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `deployment` | `string` | Yes | The prompt deployment name |
| `variant` | `string` | No | The deployment variant name |
| `inputs` | `Record` | No | Key-value pairs for the prompt variables |
| `user` | `string` | No | Opaque caller identifier surfaced in [User Tracking](../user-tracking/overview) |
| `metadata` | `Record` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
The SDK injects `streaming: false` for `invokePrompt`. To stream, use `invokePromptStream` (below).
## Handling the response
```typescript theme={null}
const result = await client.invokePrompt({
deployment: 'my-prompt',
variant: 'default',
});
console.log(result.response); // final text
console.log(result.model); // model identifier
console.log(result.usage); // token usage breakdown
console.log(result.request_id); // use this to look up the run in Logs
```
## Streaming
Use `invokePromptStream` to receive Server-Sent Events as they arrive. The method returns an `AsyncIterable` that you can consume with `for await`:
```typescript theme={null}
for await (const chunk of client.invokePromptStream({
deployment: 'YOUR_DEPLOYMENT_NAME',
variant: 'YOUR_VARIANT_NAME',
inputs: { text: 'Fetch Hive helps teams ship AI products faster.' },
})) {
if (chunk.type === 'response') {
process.stdout.write(chunk.response ?? '');
} else if (chunk.type === 'usage') {
console.log('\n\nUsage:', chunk.usage);
}
}
```
The stream yields the same event types documented in [Invoke Prompt → Response](../api-reference/prompts/invoke#response): `reasoning`, `response`, a final `usage` event, or an `error` event if the provider fails mid-stream.
## Configuration
| Option | Default | Description |
| --------- | -------------------------------- | ------------------------------- |
| `apiKey` | `process.env.FETCH_HIVE_API_KEY` | Bearer token from the dashboard |
| `baseURL` | `https://api.fetchhive.com/v1` | Override the API base URL |
```typescript theme={null}
const client = new FetchHive({
apiKey: 'fhk_...',
baseURL: 'https://api.fetchhive.com/v1',
});
```
## Errors
Non-2xx responses throw an `Error` whose message includes the status code and response body:
```typescript theme={null}
try {
const result = await client.invokePrompt({
deployment: 'my-prompt',
variant: 'default',
});
} catch (err) {
console.error('Fetch Hive error:', err);
}
```
See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for status code meanings.
## Links
* [Package on npm](https://www.npmjs.com/package/@fetch-hive/sdk)
* [Source on GitHub](https://github.com/Fetch-Hive/nodejs-sdk)
## Next steps
* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Invoke Prompt](../api-reference/prompts/invoke) - Full endpoint reference
# Run with PHP SDK
Source: https://docs.fetchhive.com/prompts/run-with-php-sdk
Invoke a prompt deployment from PHP with the fetch-hive/sdk Composer package
Use the official `fetch-hive/sdk` Composer package when you want to invoke a prompt deployment from PHP. The SDK wraps the public [`POST /v1/prompt/invoke`](../api-reference/prompts/invoke) endpoint with an idiomatic facade, handles authentication, and exposes streaming responses as a generator of parsed event arrays.
## Installation
```bash theme={null}
composer require fetch-hive/sdk
```
The SDK requires PHP 8.1+ and uses Guzzle as its HTTP client.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the client reads it automatically):
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```php theme={null}
'fhk_...']);
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Invoke a prompt deployment and read the final response:
```php theme={null}
invokePrompt([
'deployment' => 'YOUR_DEPLOYMENT_NAME',
'variant' => 'YOUR_VARIANT_NAME',
'inputs' => ['text' => 'Fetch Hive helps teams ship AI products faster.'],
]);
echo $result['response'];
```
`invokePrompt` blocks until the prompt completes and returns the parsed JSON body as an associative array. See the [non-streaming response shape](../api-reference/prompts/invoke#response).
## Method reference
| Key | Type | Required | Description |
| ------------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `deployment` | `string` | Yes | The prompt deployment name |
| `variant` | `string` | No | The deployment variant name |
| `inputs` | `array` | No | Key-value pairs for the prompt variables |
| `user` | `string` | No | Opaque caller identifier surfaced in [User Tracking](../user-tracking/overview) |
| `metadata` | `array` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
The SDK injects `streaming: false` for `invokePrompt`. To stream, use `invokePromptStream` (below).
## Handling the response
```php theme={null}
$result = $client->invokePrompt([
'deployment' => 'my-prompt',
'variant' => 'default',
]);
echo $result['response']; // final text
echo $result['model']; // model identifier
print_r($result['usage']); // token usage breakdown
echo $result['request_id']; // use this to look up the run in Logs
```
## Streaming
Use `invokePromptStream` to receive Server-Sent Events as they arrive. The method returns a `Generator` you can iterate with `foreach`:
```php theme={null}
foreach ($client->invokePromptStream([
'deployment' => 'YOUR_DEPLOYMENT_NAME',
'variant' => 'YOUR_VARIANT_NAME',
'inputs' => ['text' => 'Fetch Hive helps teams ship AI products faster.'],
]) as $chunk) {
match ($chunk['type']) {
'response' => print($chunk['response'] ?? ''),
'usage' => print("\n\nUsage: " . json_encode($chunk['usage'])),
default => null,
};
}
```
The stream yields the same event types documented in [Invoke Prompt → Response](../api-reference/prompts/invoke#response): `reasoning`, `response`, a final `usage` event, or an `error` event if the provider fails mid-stream.
## Configuration
| Option | Default | Description |
| ---------- | ------------------------------ | ------------------------------- |
| `api_key` | `FETCH_HIVE_API_KEY` env var | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL |
| `timeout` | `120` | Request timeout in seconds |
```php theme={null}
$client = new FetchHive([
'api_key' => 'fhk_...',
'base_url' => 'https://api.fetchhive.com/v1',
'timeout' => 60.0,
]);
```
## Errors
Non-2xx responses throw `FetchHive\Sdk\Exception\ApiException` carrying the status code and response body. Catch it if you need to handle failures:
```php theme={null}
use FetchHive\Sdk\Exception\ApiException;
try {
$result = $client->invokePrompt([
'deployment' => 'my-prompt',
'variant' => 'default',
]);
} catch (ApiException $e) {
error_log('Fetch Hive error: ' . $e->getMessage());
}
```
See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for status code meanings.
## Links
* [Package on Packagist](https://packagist.org/packages/fetch-hive/sdk)
* [Source on GitHub](https://github.com/Fetch-Hive/php-sdk)
## Next steps
* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Invoke Prompt](../api-reference/prompts/invoke) - Full endpoint reference
# Run with Python SDK
Source: https://docs.fetchhive.com/prompts/run-with-python-sdk
Invoke a prompt deployment from Python with the fetch-hive-sdk package
Use the official `fetch-hive-sdk` package when you want to invoke a prompt deployment from Python. The SDK wraps the public [`POST /v1/prompt/invoke`](../api-reference/prompts/invoke) endpoint with idiomatic helpers, handles authentication, and parses streaming responses for you.
## Installation
```bash theme={null}
pip install fetch-hive-sdk
```
The SDK requires Python 3.9+ and uses `httpx` under the hood.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the SDK reads it automatically):
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```python theme={null}
from fetch_hive_sdk import FetchHive
client = FetchHive()
```
Or pass the key explicitly:
```python theme={null}
client = FetchHive(api_key="fhk_...")
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Invoke a prompt deployment and read the final response:
```python theme={null}
from fetch_hive_sdk import FetchHive
client = FetchHive()
result = client.invoke_prompt(
deployment="YOUR_DEPLOYMENT_NAME",
variant="YOUR_VARIANT_NAME",
inputs={"text": "Fetch Hive helps teams ship AI products faster."},
)
print(result["response"])
```
`invoke_prompt` is synchronous and returns the parsed JSON body once the prompt has completed. See the [non-streaming response shape](../api-reference/prompts/invoke#response).
## Method reference
| Argument | Type | Required | Description |
| ------------ | ------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `deployment` | `str` | Yes | The prompt deployment name |
| `variant` | `str` | No | The deployment variant name |
| `inputs` | `dict[str, Any]` | No | Key-value pairs for the prompt variables |
| `user` | `str` | No | Opaque caller identifier surfaced in [User Tracking](../user-tracking/overview) |
| `metadata` | `dict[str, str \| int \| float \| bool \| None]` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
The SDK injects `streaming: false` for `invoke_prompt`. To stream, use `invoke_prompt_stream` (below).
## Handling the response
The non-streaming response is a plain `dict`:
```python theme={null}
result = client.invoke_prompt(deployment="my-prompt", variant="default")
print(result["response"]) # final text
print(result["model"]) # model identifier
print(result["usage"]) # token usage breakdown
print(result["request_id"]) # use this to look up the run in Logs
```
## Streaming
Use `invoke_prompt_stream` to receive Server-Sent Events as they arrive. The method returns a generator that yields parsed event dicts:
```python theme={null}
for chunk in client.invoke_prompt_stream(
deployment="YOUR_DEPLOYMENT_NAME",
variant="YOUR_VARIANT_NAME",
inputs={"text": "Fetch Hive helps teams ship AI products faster."},
):
if chunk.get("type") == "response":
print(chunk.get("response", ""), end="", flush=True)
elif chunk.get("type") == "usage":
print("\n\nUsage:", chunk["usage"])
```
The stream yields the same event types documented in [Invoke Prompt → Response](../api-reference/prompts/invoke#response): `reasoning`, `response`, a final `usage` event, or an `error` event if the provider fails mid-stream.
### Async streaming
For `asyncio` applications, use `ainvoke_prompt_stream`. It has the same arguments but returns an async iterator:
```python theme={null}
import asyncio
from fetch_hive_sdk import FetchHive
async def main():
client = FetchHive()
async for chunk in client.ainvoke_prompt_stream(
deployment="YOUR_DEPLOYMENT_NAME",
variant="YOUR_VARIANT_NAME",
inputs={"text": "Hello"},
):
if chunk.get("type") == "response":
print(chunk.get("response", ""), end="", flush=True)
asyncio.run(main())
```
## Configuration
| Option | Default | Description |
| ---------- | ------------------------------ | ------------------------------- |
| `api_key` | `FETCH_HIVE_API_KEY` env var | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL |
| `timeout` | `120` | Request timeout in seconds |
```python theme={null}
client = FetchHive(
api_key="fhk_...",
base_url="https://api.fetchhive.com/v1",
timeout=60,
)
```
## Errors
Non-2xx responses raise an `httpx.HTTPStatusError` with the status code and response body. Wrap calls in `try`/`except` if you need to handle failures:
```python theme={null}
import httpx
try:
result = client.invoke_prompt(deployment="my-prompt", variant="default")
except httpx.HTTPStatusError as exc:
print("Fetch Hive returned", exc.response.status_code, exc.response.text)
```
See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for status code meanings.
## Links
* [Package on PyPI](https://pypi.org/project/fetch-hive-sdk/)
* [Source on GitHub](https://github.com/Fetch-Hive/python-sdk)
## Next steps
* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Invoke Prompt](../api-reference/prompts/invoke) - Full endpoint reference
# Run with Ruby SDK
Source: https://docs.fetchhive.com/prompts/run-with-ruby-sdk
Invoke a prompt deployment from Ruby with the fetch_hive gem
Use the official `fetch_hive` gem when you want to invoke a prompt deployment from Ruby. The SDK wraps the public [`POST /v1/prompt/invoke`](../api-reference/prompts/invoke) endpoint with idiomatic helpers, handles authentication, and parses streaming responses into yielded hashes.
## Installation
Add to your `Gemfile`:
```ruby theme={null}
gem "fetch_hive"
```
Then run:
```bash theme={null}
bundle install
```
Or install directly:
```bash theme={null}
gem install fetch_hive
```
The gem uses `faraday` under the hood and supports Ruby 3.0+.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the client reads it automatically):
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```ruby theme={null}
require "fetch_hive"
client = FetchHive::Client.new
```
Or pass the key explicitly:
```ruby theme={null}
client = FetchHive::Client.new(api_key: "fhk_...")
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Invoke a prompt deployment and read the final response:
```ruby theme={null}
require "fetch_hive"
client = FetchHive::Client.new
result = client.invoke_prompt(
deployment: "YOUR_DEPLOYMENT_NAME",
variant: "YOUR_VARIANT_NAME",
inputs: { text: "Fetch Hive helps teams ship AI products faster." }
)
puts result["response"]
```
`invoke_prompt` blocks until the prompt completes and returns the parsed JSON body as a hash. See the [non-streaming response shape](../api-reference/prompts/invoke#response).
## Method reference
| Keyword | Type | Required | Description |
| ------------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `deployment` | `String` | Yes | The prompt deployment name |
| `variant` | `String` | No | The deployment variant name |
| `inputs` | `Hash` | No | Key-value pairs for the prompt variables |
| `user` | `String` | No | Opaque caller identifier surfaced in [User Tracking](../user-tracking/overview) |
| `metadata` | `Hash` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
The SDK injects `streaming: false` for `invoke_prompt`. To stream, use `invoke_prompt_stream` (below).
## Handling the response
```ruby theme={null}
result = client.invoke_prompt(deployment: "my-prompt", variant: "default")
puts result["response"] # final text
puts result["model"] # model identifier
puts result["usage"] # token usage breakdown
puts result["request_id"] # use this to look up the run in Logs
```
## Streaming
Use `invoke_prompt_stream` to receive Server-Sent Events as they arrive. The method yields each parsed event hash to the block:
```ruby theme={null}
client.invoke_prompt_stream(
deployment: "YOUR_DEPLOYMENT_NAME",
variant: "YOUR_VARIANT_NAME",
inputs: { text: "Fetch Hive helps teams ship AI products faster." }
) do |chunk|
case chunk["type"]
when "response"
print chunk["response"]
$stdout.flush
when "usage"
puts "\n\nUsage: #{chunk['usage']}"
end
end
```
The stream yields the same event types documented in [Invoke Prompt → Response](../api-reference/prompts/invoke#response): `reasoning`, `response`, a final `usage` event, or an `error` event if the provider fails mid-stream.
If you omit the block, the method returns an `Enumerator` you can pass around:
```ruby theme={null}
enum = client.invoke_prompt_stream(deployment: "my-prompt", variant: "default")
enum.each { |chunk| handle(chunk) }
```
## Configuration
| Option | Default | Description |
| ---------- | ------------------------------ | ------------------------------- |
| `api_key` | `ENV["FETCH_HIVE_API_KEY"]` | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL |
| `timeout` | `120` | Request timeout in seconds |
```ruby theme={null}
client = FetchHive::Client.new(
api_key: "fhk_...",
base_url: "https://api.fetchhive.com/v1",
timeout: 60
)
```
## Errors
Non-2xx responses raise a `RuntimeError` with the status code and body. Rescue them if you need to handle failures:
```ruby theme={null}
begin
result = client.invoke_prompt(deployment: "my-prompt", variant: "default")
rescue => e
warn "Fetch Hive error: #{e.message}"
end
```
See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for status code meanings.
## Links
* [Gem on RubyGems](https://rubygems.org/gems/fetch_hive)
* [Source on GitHub](https://github.com/Fetch-Hive/ruby-sdk)
## Next steps
* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Invoke Prompt](../api-reference/prompts/invoke) - Full endpoint reference
# Callback Delivery and Webhook Triggers
Source: https://docs.fetchhive.com/workflows/async-and-webhooks
Start workflow deployments with API invoke or webhook triggers, send results to callback URLs, and verify signed callback delivery
Fetch Hive separates how a run starts from how the result comes back:
* **API invoke** starts a run through `POST /v1/workflow/invoke` with a workspace API key.
* **Webhook trigger** starts a deployed variant through `POST /v1/workflow/webhooks/...` with the deployment webhook secret.
* **Callback delivery** returns immediately and later sends a signed completion event to `async.callback_url`.
The request field is still named `async` for API compatibility, but the product behavior is callback delivery.
## Overview
The workflow deployment helper exposes API invocation and webhook triggering for the selected deployment variant. Webhook triggers use the deployment webhook secret and do not require a workspace API key.
API invoke requests can choose direct delivery or callback delivery. When you include `async.callback_url`, Fetch Hive returns immediately and later delivers a signed callback event to that URL.
Webhook triggers always use callback delivery. They require `async.callback_url`, return quickly, and deliver the final result only through the signed callback event.
The same deployment secret is used in both directions. A caller proves it can start the deployed workflow by sending the secret in `X-Fetch-Hive-Webhook-Secret`. Your callback receiver proves the later event came from Fetch Hive by verifying `X-Fetch-Hive-Signature` with HMAC SHA256 and that same secret.
## How do I trigger a workflow by webhook?
Open **More** in the workflows sidebar and click **Get Code**, or open **Code Snippet** from a workflow deployment page.
Select the **Deployment** and **Variant** you want to trigger, then open the **Webhook trigger** tab.
Copy the webhook URL and send a `POST` request with the deployment secret in `X-Fetch-Hive-Webhook-Secret`:
```bash theme={null}
curl 'https://api.fetchhive.com/v1/workflow/webhooks/YOUR_WORKFLOW_ENDPOINT_ID/variants/YOUR_VARIANT_ID' \
-H 'X-Fetch-Hive-Webhook-Secret: YOUR_WEBHOOK_SECRET' \
-H 'Content-Type: application/json' \
--data-raw '{
"inputs": {
"topic": "State of enterprise AI in 2026"
},
"async": {
"callback_url": "https://example.com/callback"
}
}'
```
If your webhook provider cannot send custom headers, you can pass `?secret=YOUR_WEBHOOK_SECRET` as a fallback. Prefer the header whenever the provider supports it.
Use the deployment webhook secret shown in the helper. This is the same secret Fetch Hive uses to sign callback delivery events for this deployment.
When the body has an `inputs` object, Fetch Hive uses that object as the workflow start inputs. If the body is a JSON object without `inputs`, Fetch Hive treats the whole object as workflow inputs.
You can also include optional `user` and `metadata` fields beside `inputs`. The `async.callback_url` field is required:
```json theme={null}
{
"inputs": {
"topic": "State of enterprise AI in 2026"
},
"user": {
"id": "user_123",
"email": "person@example.com"
},
"metadata": {
"source_system": "zapier"
},
"async": {
"callback_url": "https://example.com/callback"
}
}
```
`metadata` is caller-defined user metadata for audit and log filtering. It must be a flat object whose values are strings, numbers, booleans, or `null`; nested objects and arrays return a validation error before the run starts. To send metadata, use the wrapped body shape shown above with `metadata` beside `inputs`. If you omit `inputs`, the whole JSON object is treated as workflow inputs, so `metadata` is not extracted as log-filter metadata.
Webhook-triggered runs appear under **Source: Webhook** in workflow logs and show **Delivery: Callback** with callback delivery logs.
## How do I enable callback delivery for API invoke?
Open **More** in the workflows sidebar and click **Get Code**, or open **Code Snippet** from a workflow deployment page.
Select the **Deployment** and **Variant** you want to invoke.
Turn on **Callback delivery**.
The cURL snippet updates to include:
```json theme={null}
{
"async": {
"enabled": true,
"callback_url": "https://example.com/callback"
}
}
```
Replace the example callback URL with your real webhook endpoint before you run the request.
## How do I verify callback signatures?
Turn on **Callback delivery** in the code snippet dialog, or open the **Webhook trigger** tab.
Copy the **Signing secret** shown below the snippet, or view the same secret from the workflow deployment details page.
When your server receives the callback event, verify the `X-Fetch-Hive-Signature` header using HMAC SHA256 and that signing secret.
Treat any callback event that fails signature verification as untrusted.
If the workflow was started by the webhook trigger, this signing secret is the same value the triggering system sent in `X-Fetch-Hive-Webhook-Secret`. The inbound trigger check is a bearer-style secret check; the outbound callback check is HMAC signature verification.
## What response do I get from callback delivery?
When callback delivery is enabled, the public route returns immediately instead of waiting for the workflow output.
For direct delivery, the public API waits only within the sync timeout window.
If a workflow exceeds that window, Fetch Hive requests cancellation and returns
`504` with the `request_id` and `run_status: "failed"`. Use callback delivery
for long-running workflows or workflows that include Human in the Loop steps.
The API invoke route can return a `running` state:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"run_status": "running",
"webhook_secret": "YOUR_WEBHOOK_SECRET"
}
```
At high concurrency, it can also return a `queued` state:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"run_status": "queued",
"webhook_secret": "YOUR_WEBHOOK_SECRET"
}
```
Use the returned `request_id` for your own request tracking, and rely on callback delivery for the final result.
Workflow webhook triggers also return quickly:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"run_status": "running"
}
```
## What validation rules apply to callback delivery?
If `async.enabled` is `true`, `callback_url` is required.
Webhook triggers always require `async.callback_url`.
Fetch Hive also validates that `callback_url` is a valid URL.
Workflows that contain a Human in the Loop step always require callback delivery, even for API invoke requests. They cannot complete synchronously because Fetch Hive pauses the workflow until the selected workspace member responds.
For example, these errors are explicitly confirmed:
```json theme={null}
{
"error": "callback_url is required when async is enabled"
}
```
```json theme={null}
{
"error": "callback_url must be a valid URL"
}
```
## What callback events does Fetch Hive emit?
Every callback delivery has the same envelope:
```json theme={null}
{
"event_type": "",
"request_id": "req_...",
"data": { "...": "..." }
}
```
The `event_type` field tells you which terminal state the workflow reached:
* `workflow.completed` - the workflow finished successfully. `data.output` contains the final output value.
* `workflow.failed` - the workflow errored during execution. `data.error` contains the error message.
* `workflow.cancelled` - the workflow was cancelled before it could complete, either by a user in the Fetch Hive dashboard or directly via the orchestrator. `data.error` contains the cancellation reason, and `data.reason` is always the string `"cancelled"` so you can branch without parsing the message.
For image-generation workflows, `workflow.completed` includes a structured output object:
* `data.output.settings` (model and settings used)
* `data.output.assets` (generated uploaded assets)
Example `workflow.cancelled` payload:
```json theme={null}
{
"event_type": "workflow.cancelled",
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"data": {
"error": "Workflow cancelled: Activity canceled",
"reason": "cancelled"
}
}
```
Treat `workflow.cancelled` as a terminal state on your side. No further callback event will be delivered for that `request_id`. The workflow run's partial progress, including any completions that finished before the cancel, is still available via the run detail view and the [Logs](./logs) endpoints.
## Where do I inspect callback delivery after it starts?
Use [Logs](./logs) after the workflow starts.
The workflow run detail view can show the **Callback** badge, **Callback delivery** section, output, and **Webhook Logs** for runs that used callback delivery. **Webhook Logs** are callback delivery attempts, not the run source.
If callback delivery fails, the logs view can also show retry history and response details for each delivery attempt.
## Notes
Webhook triggers, API invoke requests with callback delivery, and signed callback events are separate parts of the workflow lifecycle. A webhook trigger starts a run. Callback delivery controls whether Fetch Hive returns immediately and stores a callback URL. The signed callback event is how the final result reaches that callback URL later.
If you do not need callback delivery, keep it disabled and use the normal direct response documented in [Run with API](./run-with-api).
See also: [Run with API](./run-with-api), [Logs](./logs), and [Error Handling](./error-handling)
# Creating and Editing
Source: https://docs.fetchhive.com/workflows/creating-and-editing
Create a workflow, add steps on the canvas, configure start inputs, and work with step settings
Use the workflow editor when you want to build a multi-step flow inside the dashboard. You start from the **Workflows** list, open the canvas, add steps between **Start** and **End**, and configure each step from **Step settings**.
## Overview
The workflow builder is a canvas-based editor under **Workflows**. Each workflow starts with **Start** and **End**. Add steps with the `+` connectors on the canvas, or click **Add Step** in the bottom control bar to append a new step before **End**.
You can add a step, edit its settings, add **Start** inputs, run a single step, duplicate a step, remove a step, disable or enable a step, and drag steps onto insert points to reposition them while you iterate. You can also duplicate an entire workflow from the editor breadcrumb menu.
## How do I create a workflow?
Open **Workflows** in the sidebar.
Click **Add Workflow**.
Enter a name for the workflow. If your workspace uses categories, you can also choose a category.
Click **Save** to open the workflow editor.
## How do I duplicate a workflow?
Open the workflow in the editor.
Open the workflow name menu in the breadcrumb and choose **Duplicate**.
Confirm the action. Fetch Hive creates a copy named after the original with `(Copy)` appended, keeps the same step graph (including condition branches and iteration loops), and clears previous run output so the copy starts fresh. Deployments and schedules stay on the original workflow and are not copied.
## How do I add a step on the canvas?
Open the workflow in the editor.
Start from the default canvas with **Start** at the top and **End** at the bottom.
To insert a step between two existing nodes, click the `+` connector on that edge. To append a step at the end of the workflow (just before **End**), click **Add Step** in the bottom control bar.
Either action opens **Search steps...**.
Choose the step you want. The current picker groups steps under categories such as **AI**, **Research**, **Microsoft**, **Generation**, **Utilities**, and **Integrations**.
After you select a step, Fetch Hive inserts it into the workflow and opens **Step settings** for that new step.
## How do I reorder steps on the canvas?
Drag a step card onto any insert point on the canvas — the `+` buttons between steps, an empty-branch placeholder, a convergence `+`, or the slot after an iteration's **Complete** label. Neighbouring steps slide apart to preview where the step will land; drop to confirm.
You can move plain steps along the main spine, into or out of a condition branch, and into or out of an iteration body. You can also drag a **condition** or **iteration** header — its branches or body move with it. You cannot drag **Start** or **End**. A **condition** can live inside an iteration body; nested **iteration** headers and Human in the Loop steps cannot. Reordering is also disabled while a workflow run is in progress.
Variable references are not rewritten automatically. If a moved step still references another step that now runs later — or now sits inside an iteration and runs once per item — update those references in **Step settings**.
## How do I add integration steps with Copilot?
Ask Workflow Copilot for the outcome you want and name the app when it matters,
for example, "Add a Gmail step that sends the summary from the previous step."
Copilot searches the integration actions currently available to your workspace,
checks the selected action's required fields, and proposes a configured step.
Review the proposed action, including its position in the workflow, then click
**Apply**. Copilot uses only available actions and exact action requirements. It
doesn't guess hidden action names or connection IDs.
You can also ask the dashboard assistant to create a complete workflow that
contains integration steps. It follows the same action lookup before proposing
the workflow.
If the selected app isn't connected, the step can still be added. Open
**Step settings**, connect or select the account under **Authentication**, and
complete any missing fields before you test, run, version, or deploy the
workflow.
## Can the dashboard assistant use an existing workflow template?
Yes. When you ask the dashboard assistant to build a workflow, it can look at
templates available to your account as reference — name, description, and the
kinds of steps they include — and then propose a new workflow for you to
**Confirm**. It does not install a template as-is from chat.
To reuse a template without rewriting it, open **Workflows > Templates** and
choose **Use template**, or open a saved workflow in the editor and choose
**Save as template** first. After creation, review each step and finish any
required **Authentication** settings before testing or running the workflow.
## How do I save and reuse a workflow as a template?
Open a saved workflow in the editor, wait until its status shows **Saved**, open
the menu beside the workflow name, and choose **Save as template**. Enter a
template name and description. Both fields are required. The saved template is
immediately available to everyone in your account, across workspaces. Select
**Save**, or press **Ctrl+Enter** on Windows/Linux or **Command+Enter** on macOS.
Turn on **Submit to Marketplace** if you also want Fetch Hive staff to review it
for the public marketplace. Your private account template is still saved
immediately. Fetch Hive creates a separate review copy and removes connected
account identifiers, private resource selections, custom headers, request bodies,
private URLs, and uploaded assets. A pending or rejected review copy is never
shown in the template gallery; approval publishes it as a global template.
Open **Workflows > Templates** to browse your account templates and approved
global marketplace templates in one list. Templates show their public author
username when available; staff-authored marketplace templates show as Fetch Hive.
After a marketplace submission is approved, the private account copy is hidden
from this combined gallery so you only see the published marketplace card (your
account still keeps the private copy). Choose **View details** to inspect the
included steps, or **Use template** to name the new workflow, choose its
category, and install it in the current workspace. Review step settings and
connect any required **Authentication** before running the new workflow.
## How do I configure start inputs and step settings?
Click **Start** to open the start step settings.
Use **Add Input** to define the variables your workflow run should accept. For each input, set the display name, variable name, input type, and whether it is required.
Start inputs can be **Text** or **Array**. Use **Text** for a single value. Use **Array** when the caller should pass a JSON array, such as `["one", "two"]` or `[{"url":"https://example.com"}]`.
Start inputs can also include an optional **Example value**. Examples are design-time only: they help the editor preview variables and wire later steps before any workflow run exists, but they are not default run values and do not spend tasks.
Use the sample input actions beside **Example value** to load a saved example or save the current example for reuse.
For array inputs, use an example JSON array that matches the shape callers will provide. For example, `[{"name":"Fetch Hive","url":"https://fetchhive.com"}]` lets an **Iteration** step use `{{companies}}` as its iterator and lets steps inside the iteration reference fields such as `{{company_loop.item.url}}` before the workflow has run.
Click any non-terminal step on the canvas to open **Step settings** for that step.
The exact settings depend on the step type. For example, **AI Prompt** exposes its prompt messages, model parameters, response format options, and failure behavior in the same sheet. When an **AI Prompt** step uses an Anthropic Claude model, its model parameters also include **Prompt Cache** with **Disabled**, **5 minutes**, and **1 hour** options.
If an AI-backed workflow step uses a retired model, the step settings show a warning and step tests or workflow runs are blocked with `model_deprecated`. Choose an active model on the step before running the workflow.
Some read-only steps can run multiple versions at the same time: Google Search, Google News, Google AI Mode, Google AI Overview, Bing Search, Exa Search, Exa Similar, Copilot Search, Website Scrape, and RSS Feed. Turn on **Parallelization** in the step settings, add the versions you want to run, and set only the fields that should differ between versions.
When the workflow runs, Fetch Hive waits for every version to finish and stores the step output as an array in version order. Later steps can reference that array with `{{step_2.output}}`. To reach a field that exists on each version's result object, use the `*` wildcard pluck: `{{step_2.output.*.field}}`. A bare field name on the array (for example `{{step_2.output.items}}`) resolves to null.
The `*` pluck does **not** flatten nested arrays. For a parallelized **RSS Feed** step, `{{rss_step.output.*.items}}` is an array of item-arrays. Add a **Data Transform** step with mode **Flatten array** and that expression as the source, then point an **Iteration** iterator at the flatten step's `{{step_N.output}}`.
Parallelization is not available for steps inside an **Iteration** body. If you need multiple search or fetch versions, run that parallelized step before the iteration and iterate over its output (flattening first when the plucked path is nested), or keep the steps inside the loop non-parallel.
Your plan controls how many versions a single step can run in parallel. If a version fails and the step is set to **Continue**, Fetch Hive omits that failed version from the output array and keeps successful versions in order. If no versions succeed, the output is an empty array. If the step is set to **Terminate Workflow**, the workflow stops.
For Iteration steps, the iteration's own failure behavior controls the loop body. If the iteration is set to **Continue**, a failed body step stops that item and leaves `null` for that item in the iteration output, even if the body step is set to **Terminate Workflow**. If the iteration is set to **Terminate Workflow**, any failed body step stops the workflow.
Use **When the step fails** when you need to decide whether the workflow should stop or continue after a step error.
## How do I edit, duplicate, disable, or remove a step?
Hover over a step node on the canvas to reveal the step actions.
Use **Run Step** when you want to test that step from the canvas.
Use **Disable step** or **Enable step** to control whether the step participates in the workflow. Disabled steps are skipped on the main path, inside condition branches, and inside iteration loops. **Run Step** still runs that step alone for testing even if it is disabled.
Use **Duplicate step** to insert a copy of the current step into the workflow.
Use **Remove step** if you want to delete the step. Fetch Hive asks you to confirm before it removes it.
See also: [Testing and Iteration](./testing-and-iteration) and [Publishing and Versioning](./publishing-and-versioning)
# Error Handling
Source: https://docs.fetchhive.com/workflows/error-handling
Understand workflow invoke errors, control step failure behavior, and debug failed runs with workflow logs and traces
Use workflow error handling docs when a workflow request fails, a step behaves unexpectedly, or callback delivery does not complete the way you expect. The goal is to separate request validation problems from workflow runtime failures so you know where to look next.
## Overview
Workflow failures happen at two different layers. The first layer is request validation on the public invoke route. The second layer is workflow execution after the run starts.
For execution failures, the most useful debugging surface is [Logs](./logs), where you can inspect the run detail sheet, trace waterfall, output, and callback delivery attempts.
## How do I handle workflow invoke request errors?
Start with the response body from `POST /v1/workflow/invoke`.
The current public route explicitly returns validation errors when required invoke fields are missing or invalid.
Examples:
```json theme={null}
{
"error": "Missing required field: deployment or variant"
}
```
```json theme={null}
{
"error": "callback_url is required when async is enabled"
}
```
```json theme={null}
{
"error": "callback_url must be a valid URL"
}
```
Fix these request-level problems first before you inspect the workflow itself.
## How do I control what happens when a workflow step fails?
Open the workflow in the editor.
Click a step to open **Step settings**.
For step types that expose the setting, use **When the step fails** to choose whether the workflow should stop or continue after that step fails.
Use **Terminate Workflow** when the workflow should stop immediately on that failure.
Use **Continue** when a failed step should not block the rest of the workflow.
Sub-workflow steps follow the same rule. If the child workflow fails, the Sub-workflow step is marked failed. **Terminate Workflow** stops the parent workflow, while **Continue** records the failure and lets the parent workflow keep running.
This setting affects runtime behavior, so test the workflow again after you change it.
## How do I debug a failed workflow run?
Open [Logs](./logs).
Find the failed run in the table, then open it.
Use the trace waterfall to identify where the failure happened. Check the selected span details, request details, start inputs, metadata, and output sections as you move through the run.
If the workflow used callback delivery, also inspect **Webhook Logs** for retry count, response code, payload, and response body.
This is the best way to separate a step failure from a delivery problem.
## What runtime failure states should I expect?
The current public workflow route can surface terminal failure states such as:
* `failed`
* `cancelled`
It can also return a timeout failure if the direct response route waits too long for the workflow to finish.
For example:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"run_status": "failed",
"error": "Workflow timed out"
}
```
Or:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"run_status": "cancelled",
"error": "Workflow run was cancelled"
}
```
Treat these as runtime failures, not request-format problems.
## Error handling notes
If the invoke request succeeds but the workflow later fails, go to workflow logs rather than changing the request payload first.
If the invoke request itself returns an `error` object immediately, fix that request before you spend time debugging the workflow editor.
See also: [Run with API](./run-with-api), [Callback Delivery and Webhook Triggers](./async-and-webhooks), and [Logs](./logs)
# Logs
Source: https://docs.fetchhive.com/workflows/logs
Review workflow runs, filter activity by source and delivery, inspect traces, and debug callback delivery
Workflow logs help you inspect what happened after a run starts, whether that run came from the dashboard, API, schedule, webhook trigger, or agent. Use this page to review recent workflow activity, filter the runs you care about, and open a run detail sheet with trace data and output.
## Overview
The workflows logs UI is a table-driven view under **Logs** in the workflows section. It supports source filtering from the sidebar, date range filtering from the header, and row-level inspection through a detailed run sheet.
When you open a completed run, the detail sheet combines summary data, a trace waterfall, request details, output, start inputs, and callback delivery information when present.
## How do I open workflow logs?
From the workflow editor, click **Logs** in the bottom control bar.
Or open **Workflows** in the sidebar and click **Logs** in the workflows section menu.
Use the **Source** group in the sidebar when you want to switch between **All Sources**, **Dashboard**, **API**, **Scheduled**, **Webhook**, and **Agent**.
Use **Dashboard** when you only want runs started from the editor or dashboard UI. Use **API** when you only want runs started from a workflow deployment through the public API. Use **Scheduled**, **Webhook**, and **Agent** for runs launched by those origins.
## What can I filter in workflow logs?
Use the date range control in the header to choose a custom range or an available preset. Presets include ranges such as the last one, seven, 30, or 90 days, but longer ranges may require a plan with more log history.
Use **API keys** to narrow the table to runs started with one or more workspace API keys.
Use **Workflow** when you want to isolate runs for a single workflow.
Use **Delivery** to switch between **All**, **Callback**, and **Direct** runs. Delivery is separate from source: an API invoke run can use callback delivery, while webhook-triggered runs always use callback delivery.
Use **User metadata** to filter by a tracked metadata property. Choose a property key to find runs where that key exists, or add an exact value to match scalar values such as `cus_123`, `enterprise`, `true`, or `12`.
Click **Clear filters** to reset the active filter state.
## What's tracked in the workflow logs table?
The main logs table shows summary fields for each run, including:
* **Completed At**
* **Name**
* **Tools**
* **Status**
* **Total Cost**
* **Duration**
* **API Key**
* **Collaborator**
For live runs, the **Name** column can also show the deployment variant badge, including the variant name and version number.
The **Tools** column reflects the providers or step sources that contributed real work completions to the run. Workflow orchestration records, such as parallel step aggregation, are excluded from this summary even though they can still appear in the trace timeline.
## How do I inspect a workflow run?
Click a completed row in the logs table.
Fetch Hive opens a run detail sheet on the right.
The header shows the run ID, status, start time, deployment variant badge when present, a source badge such as **Scheduled** or **Webhook**, and a **Callback** badge when the run uses callback delivery.
The summary strip below shows the workflow, duration, cost, tools, and owner for that run.
If the workflow still exists and is not archived, the workflow name in the summary strip links back to the workflow editor.
## Traces
Use the trace waterfall on the left side of the run detail sheet to understand how the run progressed over time.
Each span helps you inspect a specific part of the run, such as the incoming request, workflow start, tool activity, LLM activity, and workflow completion.
When you select a span, the right side updates to show the span details and any linked completion data. Depending on the selected span, this can include:
* integration action name for connected-provider action steps
* model response data
* request details
* start inputs
* output content
* user metadata
* metadata
* token and cost breakdowns
For Claude AI prompt completions, request details can include **Prompt Cache**, which is the configured Anthropic prompt-cache TTL assigned to that step run. Actual cache reads and writes are still shown through the cached-token usage fields.
This is the main debugging view for workflow runs. Start here when you need to understand which part of the workflow was slow, failed, or produced the wrong result.
## How do I inspect output, callback delivery, and webhook logs?
Open a run from the logs table.
Select the request or completion spans in the trace panel to switch the right-side details.
Use the output section when you want to inspect the final workflow result from the **workflow\.complete** span. Copyable log cards include controls to copy the displayed content or minimize the card while you compare other run details.
If the run uses callback delivery, the request-level details can also show **Callback delivery** with the callback URL used for that run.
If webhook delivery logs are present, the same sheet can show **Webhook Logs** with callback URL, retry count, response code, payload, response body, and a **Retry** action for failed callback delivery attempts. Webhook logs are delivery attempts, not the run source.
## Notes
* The logs table updates in response to workflow run status changes, so recent runs can refresh while you are viewing the page.
* Fetch Hive tracks user metadata property names over time from workflow invokes so the metadata filter can suggest keys your workspace has actually sent. See [Invoke metadata](../user-tracking/invoke-metadata) for request examples.
* Running rows are not the main entry point for deep inspection. Open a completed run when you want the full detail sheet and trace view.
* Callback delivery details are only visible when the selected run actually used callback delivery.
* Source tells you what started the run. Delivery tells you whether the run waited for a direct response or returned immediately for callback delivery.
See also: [Publishing and Versioning](./publishing-and-versioning), [Callback Delivery and Webhook Triggers](./async-and-webhooks), and [Run with API](./run-with-api)
# Overview
Source: https://docs.fetchhive.com/workflows/overview
Build multi-step workflows, test them in the editor, publish workflow deployments, and inspect run history
Use workflows when you need more than one model call or tool action in a fixed flow. In this section, you'll create workflows, configure **Start** inputs and steps, test runs in the editor, save versions, create workflow deployments, and inspect logs.
Workflows are different from standalone prompts under **Prompts** and chat Agents under **Agents**. A workflow gives you a canvas with **Start**, **End**, and intermediate steps such as **AI Prompt**, search steps, utility steps, and integrations. If you need a durable autonomous loop that plans nodes, verifies output, and repeats failed work, use [Hive Agents](../hive-agents/overview).
## What you'll find here
* [Creating and Editing](./creating-and-editing) - Create a workflow, add steps on the canvas, and configure **Step settings**
* [Testing and Iteration](./testing-and-iteration) - Run workflows in the editor, work with **Run History**, and iterate before publishing
* [Publishing and Versioning](./publishing-and-versioning) - Save versions, compare history, roll back changes, and manage workflow deployments
* [Scheduled Deployments](./scheduled-deployments) - Run published workflow deployment variants automatically with saved inputs
* [Run with API](./run-with-api) - Invoke a workflow deployment with the public API
* [Callback Delivery and Webhook Triggers](./async-and-webhooks) - Return immediately, receive signed callback events, and start deployments from webhook tools
* [Run with Python SDK](./run-with-python-sdk) - Invoke a workflow deployment from Python with `fetch-hive-sdk`
* [Run with Node.js SDK](./run-with-nodejs-sdk) - Invoke a workflow deployment from Node.js with `@fetch-hive/sdk`
* [Run with Ruby SDK](./run-with-ruby-sdk) - Invoke a workflow deployment from Ruby with the `fetch_hive` gem
* [Run with PHP SDK](./run-with-php-sdk) - Invoke a workflow deployment from PHP with `fetch-hive/sdk`
* [Logs](./logs) - Review workflow runs, traces, output, and webhook activity
* [Workflow Steps](./steps/overview) - Browse the available workflow step types and their configuration pages
# Publishing and Versioning
Source: https://docs.fetchhive.com/workflows/publishing-and-versioning
Save workflow versions, compare version history, roll back changes, and manage workflow deployments and variants
Use versioning to save stable checkpoints of a workflow and use deployments when you want to call that workflow outside the editor. The workflow editor keeps these actions separate so you can keep iterating in the dashboard without changing a live workflow deployment until you are ready.
## Overview
The current workflow editor exposes versioning, run, and deployment actions in the bottom control bar. You can use **Save Version** to record a named checkpoint, **Version History** to compare versions and roll back, **Run Workflow** to test in the editor, **Logs** to open run history, **Add Step** to append a step before **End**, and **Deploy** to create or update workflow deployments and variants.
In docs prose, refer to the public runtime surface as a workflow deployment. Keep the actual UI labels such as **Create a Deployment** and **Update a deployment variant** exactly as they appear in the product.
## How do I save a workflow version?
Open the workflow in the editor.
Click **Save Version** in the bottom control bar.
Enter a short description of what changed.
Click **Save** to create a named checkpoint for the current state of the workflow.
The current modal requires a description, so write something your team can understand later when you review changes or compare versions.
## How do I compare versions and roll back?
Open the workflow in the editor.
Click **Version History** in the bottom control bar.
Use the compare selector to choose an older version against the current live version.
Review the saved description, author, timestamp, and JSON diff before you make a rollback decision.
Click **Rollback** if you want to restore an earlier version. Then confirm the rollback in the confirmation dialog.
Rollback creates a new live version based on the selected version and keeps the current live version in history.
## How do I create a workflow deployment?
Open the workflow in the editor.
Click **Deploy** in the bottom control bar.
Choose **Create a Deployment**.
Enter a **Deployment key** and click **Save**.
Fetch Hive saves a snapshot of the current workflow and creates the workflow deployment. If **Go to deployment page after saving** stays enabled, the UI takes you to the deployment page for the new deployment and its initial variant.
## How do I add or update a deployment variant?
Open the workflow in the editor.
Click **Deploy** in the bottom control bar.
Choose **Add a variant to a deployment** if you want to create a new named variant from the current workflow state.
Choose **Update a deployment variant** if you want to snapshot the current workflow state into an existing variant.
In both flows, select the deployment first. When you add a variant, enter a **Variant name**. When you update a variant, select the existing variant you want to replace.
Enter a description before you save.
## What do I see on the deployments page?
Open **Deployments** from the workflows section in the sidebar.
The main table identifies each workflow deployment by **Deployment Key** and also shows **Total Requests**, **Avg Duration**, **Total Cost**, and collaborators for that deployment.
Open a deployment row when you want to inspect a specific deployment and variant in more detail.
## How do I schedule a workflow deployment?
Open a workflow deployment from the deployments page.
Click **Schedules** in the deployment header.
Create a schedule, choose the deployment variant to run, set the recurrence and timezone, optionally add a callback URL, and provide the required **Start** input values.
Schedules run the published deployment variant with the saved inputs. Scheduled runs appear in workflow logs and include metadata identifying the schedule that launched them.
For more detail, see [Scheduled Deployments](./scheduled-deployments).
## Workflow versioning and deployment notes
A workflow version and a workflow deployment variant are related, but they are not the same thing. A workflow version is an editor checkpoint. A deployment variant is part of the runtime surface you use when you invoke the workflow outside the editor.
Keep using **Run Workflow** while you are iterating in the editor. Save a version when you want a named checkpoint, and create or update a workflow deployment when you need a runtime target for your app.
See also: [Testing and Iteration](./testing-and-iteration), [Scheduled Deployments](./scheduled-deployments), [Run with API](./run-with-api), and [Logs](./logs)
# Run with API
Source: https://docs.fetchhive.com/workflows/run-with-api
Invoke a workflow deployment with the public API using your API key, deployment name, variant, and start inputs
Use the public workflow invoke endpoint when you want to run a workflow deployment from your own app or service. Create a workflow deployment in the dashboard, choose a variant, then use the deployment details in your request.
If an external product needs to start a workflow by sending a webhook directly to Fetch Hive, use the webhook trigger URL from the deployment helper instead. That flow uses `X-Fetch-Hive-Webhook-Secret` instead of a workspace API key. See [Callback Delivery and Webhook Triggers](./async-and-webhooks).
## Authentication
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
See [API Keys](../workspace/api-keys) for how to create and manage keys.
## Endpoint
`POST https://api.fetchhive.com/v1/workflow/invoke`
Before you call this endpoint, create a workflow deployment and variant from the workflow editor. See [Publishing and Versioning](./publishing-and-versioning) for that UI flow.
## Request
Use this request shape:
| Field | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| `deployment` | string | Yes | The workflow deployment key |
| `variant` | string | Yes | The deployment variant you want to run |
| `inputs` | object | No | Key-value pairs for the variables defined on the workflow's **Start** step |
| `async` | object | No | Callback delivery settings. See [Callback Delivery and Webhook Triggers](./async-and-webhooks) |
| `metadata` | object | No | Flat caller-defined metadata for audit and log filtering. This is not used as workflow input. |
`inputs` values must match the workflow's **Start** input types. Text inputs accept strings. Array inputs must be native JSON arrays, for example `"companies": [{"name":"Fetch Hive"}]`. Arrays are preserved as arrays in workflow variables and logs.
`metadata` must be flat and scalar-only: strings, numbers, booleans, or `null`. Nested objects and arrays return a validation error before the run starts.
If you include `async`, use these nested fields:
| Field | Type | Required | Description |
| -------------------- | ------- | ------------------------------------- | ----------------------------------------------------------------------------------- |
| `async.enabled` | boolean | Yes | Set to `true` to return immediately and deliver the result later by signed callback |
| `async.callback_url` | string | Yes when callback delivery is enabled | The callback URL Fetch Hive should call when the run finishes |
Workflows that contain a Human in the Loop step must use callback delivery. Set `async.enabled` to `true` and provide `async.callback_url`; synchronous invocation returns a validation error because the run pauses until the configured workspace member submits a choice.
## Basic example
```bash theme={null}
curl 'https://api.fetchhive.com/v1/workflow/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
"deployment": "YOUR_DEPLOYMENT_NAME",
"variant": "YOUR_VARIANT_NAME",
"inputs": {
"topic": "State of enterprise AI in 2026"
},
"metadata": {
"customer_id": "cus_123",
"plan": "enterprise"
}
}' \
--compressed
```
This matches the cURL snippet shown in the workflow deployment UI. The deployment UI currently shows a cURL example, and the **Python** and **TypeScript** tabs still show **Coming Soon**.
Use `metadata` for audit fields you want to see or filter in logs, such as customer IDs, plan names, regions, or experiment names. Workflow start variables belong in `inputs`. See [Invoke metadata](../user-tracking/invoke-metadata) for examples and log filtering details.
## Callback delivery example
```bash theme={null}
curl 'https://api.fetchhive.com/v1/workflow/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
"deployment": "YOUR_DEPLOYMENT_NAME",
"variant": "YOUR_VARIANT_NAME",
"async": {
"enabled": true,
"callback_url": "https://example.com/callback"
},
"inputs": {
"topic": "State of enterprise AI in 2026"
}
}' \
--compressed
```
See [Callback Delivery and Webhook Triggers](./async-and-webhooks) for how immediate responses and signed callback delivery work.
## Response
### Direct response
When you do not enable callback delivery, the public route waits for the workflow to finish and returns the final output. For example:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"run_status": "completed",
"output": "State of enterprise AI in 2026: enterprises are moving from experimentation to operational systems with stricter evaluation, governance, and tooling requirements."
}
```
### Callback delivery response
When `async.enabled` is `true`, the route returns immediately. For example:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"run_status": "running",
"webhook_secret": "YOUR_WEBHOOK_SECRET"
}
```
At high concurrency, the route can also return a queued callback-delivery state:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"run_status": "queued",
"webhook_secret": "YOUR_WEBHOOK_SECRET"
}
```
## Errors
The route returns an error object when the request is invalid or the run fails. For example:
```json theme={null}
{
"error": "Missing required field: deployment or variant"
}
```
See [Error Handling](./error-handling) for workflow-specific failure cases and [Callback Delivery and Webhook Triggers](./async-and-webhooks) for callback validation errors.
## Next steps
* [Callback Delivery and Webhook Triggers](./async-and-webhooks)
* [Error Handling](./error-handling)
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
# Run with Node.js SDK
Source: https://docs.fetchhive.com/workflows/run-with-nodejs-sdk
Invoke a workflow deployment from Node.js or TypeScript with the @fetch-hive/sdk package
Use the official `@fetch-hive/sdk` package when you want to invoke a workflow deployment from Node.js or TypeScript. The SDK wraps the public [`POST /v1/workflow/invoke`](../api-reference/workflows/invoke) endpoint, handles authentication, and supports both direct responses and callback delivery.
## Installation
```bash theme={null}
npm install @fetch-hive/sdk
# or
yarn add @fetch-hive/sdk
# or
pnpm add @fetch-hive/sdk
```
The SDK targets Node.js 18+ (uses the global `fetch`) and ships with TypeScript types.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key:
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```typescript theme={null}
import { FetchHive } from '@fetch-hive/sdk';
const client = new FetchHive();
```
Or pass the key explicitly:
```typescript theme={null}
const client = new FetchHive({ apiKey: 'fhk_...' });
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Run a workflow deployment directly. The call blocks until the workflow finishes:
```typescript theme={null}
import { FetchHive } from '@fetch-hive/sdk';
const client = new FetchHive();
const run = await client.invokeWorkflow({
deployment: 'YOUR_DEPLOYMENT_NAME',
variant: 'YOUR_VARIANT_NAME',
inputs: { topic: 'State of enterprise AI in 2026' },
});
console.log(run.status);
console.log(run.output);
```
See the [direct response shape](../api-reference/workflows/invoke#response).
## Method reference
| Field | Type | Required | Description |
| ------------ | ----------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `deployment` | `string` | Yes | The workflow deployment name |
| `variant` | `string` | No | The deployment variant name |
| `inputs` | `Record` | No | Key-value pairs for the variables defined on the **Start** step |
| `async` | `{ enabled: boolean, callback_url?: string }` | No | Callback delivery settings |
| `user` | `string` | No | Opaque caller identifier surfaced in [User Tracking](../user-tracking/overview) |
| `metadata` | `Record` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
## Handling the response
```typescript theme={null}
const run = await client.invokeWorkflow({
deployment: 'my-workflow',
variant: 'default',
});
console.log(run.status); // "completed" | "failed" | "running" | "queued"
console.log(run.output); // final workflow output
console.log(run.request_id); // use this to look up the run in Logs
```
## Callback delivery
Pass an `async` block to return immediately and have Fetch Hive call your callback URL when the run finishes:
```typescript theme={null}
const run = await client.invokeWorkflow({
deployment: 'YOUR_DEPLOYMENT_NAME',
variant: 'YOUR_VARIANT_NAME',
inputs: { topic: 'State of enterprise AI in 2026' },
async: { enabled: true, callback_url: 'https://example.com/callback' },
});
console.log('Queued:', run.status);
console.log('Webhook secret:', run.webhook_secret);
```
Store the `webhook_secret` so you can verify the signature on the incoming callback. See [Callback Delivery and Webhook Triggers](./async-and-webhooks) for the verification flow and signed payload shape.
## Configuration
| Option | Default | Description |
| --------- | -------------------------------- | ------------------------------- |
| `apiKey` | `process.env.FETCH_HIVE_API_KEY` | Bearer token from the dashboard |
| `baseURL` | `https://api.fetchhive.com/v1` | Override the API base URL |
```typescript theme={null}
const client = new FetchHive({
apiKey: 'fhk_...',
baseURL: 'https://api.fetchhive.com/v1',
});
```
For long-running direct workflow requests, prefer `async: { enabled: true, ... }` over increasing client-side timeouts.
## Errors
Non-2xx responses throw an `Error` whose message includes the status code and response body:
```typescript theme={null}
try {
const run = await client.invokeWorkflow({
deployment: 'my-workflow',
variant: 'default',
});
} catch (err) {
console.error('Fetch Hive error:', err);
}
```
See [Error Handling](./error-handling) for workflow-specific failure cases and [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for HTTP status code meanings.
## Links
* [Package on npm](https://www.npmjs.com/package/@fetch-hive/sdk)
* [Source on GitHub](https://github.com/Fetch-Hive/nodejs-sdk)
## Next steps
* [Callback Delivery and Webhook Triggers](./async-and-webhooks) - Verify callback signatures
* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Invoke Workflow](../api-reference/workflows/invoke) - Full endpoint reference
# Run with PHP SDK
Source: https://docs.fetchhive.com/workflows/run-with-php-sdk
Invoke a workflow deployment from PHP with the fetch-hive/sdk Composer package
Use the official `fetch-hive/sdk` Composer package when you want to invoke a workflow deployment from PHP. The SDK wraps the public [`POST /v1/workflow/invoke`](../api-reference/workflows/invoke) endpoint, handles authentication, and supports both direct responses and callback delivery.
## Installation
```bash theme={null}
composer require fetch-hive/sdk
```
The SDK requires PHP 8.1+ and uses Guzzle as its HTTP client.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the client reads it automatically):
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```php theme={null}
'fhk_...']);
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Run a workflow deployment directly. The call blocks until the workflow finishes:
```php theme={null}
invokeWorkflow([
'deployment' => 'YOUR_DEPLOYMENT_NAME',
'variant' => 'YOUR_VARIANT_NAME',
'inputs' => ['topic' => 'State of enterprise AI in 2026'],
]);
echo $run['run_status'] . PHP_EOL;
echo $run['output'];
```
See the [direct response shape](../api-reference/workflows/invoke#response).
## Method reference
| Key | Type | Required | Description |
| -------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `deployment` | `string` | Yes | The workflow deployment name |
| `variant` | `string` | No | The deployment variant name |
| `inputs` | `array` | No | Key-value pairs for the variables defined on the **Start** step |
| `async_mode` | `bool` | No | When `true`, return immediately and deliver the result by signed callback |
| `callback_url` | `string` | No | Required when `async_mode: true` - the HTTPS callback URL to call when the run finishes |
| `user` | `string` | No | Opaque caller identifier surfaced in [User Tracking](../user-tracking/overview) |
| `metadata` | `array` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
`invokeWorkflow` builds the request body for you. When you pass `async_mode: true`, the SDK sends:
```json theme={null}
{
"async": { "enabled": true, "callback_url": "https://example.com/webhook" }
}
```
## Handling the response
```php theme={null}
$run = $client->invokeWorkflow([
'deployment' => 'my-workflow',
'variant' => 'default',
]);
echo $run['run_status']; // "completed" | "failed" | "running" | "queued"
echo $run['output']; // final workflow output
echo $run['request_id']; // use this to look up the run in Logs
```
## Callback delivery
Pass `async_mode: true` to return immediately and have Fetch Hive call your callback URL when the run finishes:
```php theme={null}
$run = $client->invokeWorkflow([
'deployment' => 'YOUR_DEPLOYMENT_NAME',
'variant' => 'YOUR_VARIANT_NAME',
'inputs' => ['topic' => 'State of enterprise AI in 2026'],
'async_mode' => true,
'callback_url' => 'https://example.com/callback',
]);
echo 'Queued: ' . $run['run_status'] . PHP_EOL;
echo 'Webhook secret: ' . $run['webhook_secret'];
```
Store the `webhook_secret` so you can verify the signature on the incoming callback. See [Callback Delivery and Webhook Triggers](./async-and-webhooks) for the verification flow and signed payload shape.
## Configuration
| Option | Default | Description |
| ---------- | ------------------------------ | ------------------------------------------------------------------------------- |
| `api_key` | `FETCH_HIVE_API_KEY` env var | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL |
| `timeout` | `120` | Request timeout in seconds - increase for long-running direct workflow requests |
```php theme={null}
$client = new FetchHive([
'api_key' => 'fhk_...',
'base_url' => 'https://api.fetchhive.com/v1',
'timeout' => 600.0,
]);
```
## Errors
Non-2xx responses throw `FetchHive\Sdk\Exception\ApiException` carrying the status code and response body:
```php theme={null}
use FetchHive\Sdk\Exception\ApiException;
try {
$run = $client->invokeWorkflow([
'deployment' => 'my-workflow',
'variant' => 'default',
]);
} catch (ApiException $e) {
error_log('Fetch Hive error: ' . $e->getMessage());
}
```
See [Error Handling](./error-handling) for workflow-specific failure cases and [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for HTTP status code meanings.
## Links
* [Package on Packagist](https://packagist.org/packages/fetch-hive/sdk)
* [Source on GitHub](https://github.com/Fetch-Hive/php-sdk)
## Next steps
* [Callback Delivery and Webhook Triggers](./async-and-webhooks) - Verify callback signatures
* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Invoke Workflow](../api-reference/workflows/invoke) - Full endpoint reference
# Run with Python SDK
Source: https://docs.fetchhive.com/workflows/run-with-python-sdk
Invoke a workflow deployment from Python with the fetch-hive-sdk package
Use the official `fetch-hive-sdk` package when you want to invoke a workflow deployment from Python. The SDK wraps the public [`POST /v1/workflow/invoke`](../api-reference/workflows/invoke) endpoint, handles authentication, and supports both direct responses and callback delivery.
## Installation
```bash theme={null}
pip install fetch-hive-sdk
```
The SDK requires Python 3.9+ and uses `httpx` under the hood.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the SDK reads it automatically):
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```python theme={null}
from fetch_hive_sdk import FetchHive
client = FetchHive()
```
Or pass the key explicitly:
```python theme={null}
client = FetchHive(api_key="fhk_...")
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Run a workflow deployment directly. The call blocks until the workflow finishes:
```python theme={null}
from fetch_hive_sdk import FetchHive
client = FetchHive()
run = client.invoke_workflow(
deployment="YOUR_DEPLOYMENT_NAME",
variant="YOUR_VARIANT_NAME",
inputs={"topic": "State of enterprise AI in 2026"},
)
print(run["run_status"])
print(run["output"])
```
See the [direct response shape](../api-reference/workflows/invoke#response).
## Method reference
| Argument | Type | Required | Description |
| -------------- | ------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `deployment` | `str` | Yes | The workflow deployment name |
| `variant` | `str` | No | The deployment variant name |
| `inputs` | `dict[str, Any]` | No | Key-value pairs for the variables defined on the **Start** step |
| `async_mode` | `bool` | No | When `True`, return immediately and deliver the result by signed callback |
| `callback_url` | `str` | No | Required when `async_mode=True` - the HTTPS callback URL to call when the run finishes |
| `user` | `str` | No | Opaque caller identifier surfaced in [User Tracking](../user-tracking/overview) |
| `metadata` | `dict[str, str \| int \| float \| bool \| None]` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
`invoke_workflow` builds the request body for you. When you pass `async_mode=True`, the SDK sends:
```json theme={null}
{
"async": { "enabled": true, "callback_url": "https://example.com/webhook" }
}
```
## Handling the response
```python theme={null}
run = client.invoke_workflow(deployment="my-workflow", variant="default")
print(run["run_status"]) # "completed" | "failed" | "running" | "queued"
print(run["output"]) # final workflow output
print(run["request_id"]) # use this to look up the run in Logs
```
## Callback delivery
Pass `async_mode=True` to return immediately and have Fetch Hive call your callback URL when the run finishes:
```python theme={null}
run = client.invoke_workflow(
deployment="YOUR_DEPLOYMENT_NAME",
variant="YOUR_VARIANT_NAME",
inputs={"topic": "State of enterprise AI in 2026"},
async_mode=True,
callback_url="https://example.com/callback",
)
print("Queued:", run["run_status"])
print("Webhook secret:", run["webhook_secret"])
```
Store the `webhook_secret` so you can verify the signature on the incoming callback. See [Callback Delivery and Webhook Triggers](./async-and-webhooks) for the verification flow and signed payload shape.
## Configuration
| Option | Default | Description |
| ---------- | ------------------------------ | ------------------------------------------------------------------------------- |
| `api_key` | `FETCH_HIVE_API_KEY` env var | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL |
| `timeout` | `120` | Request timeout in seconds - increase for long-running direct workflow requests |
```python theme={null}
client = FetchHive(
api_key="fhk_...",
base_url="https://api.fetchhive.com/v1",
timeout=600,
)
```
## Errors
Non-2xx responses raise an `httpx.HTTPStatusError` with the status code and response body:
```python theme={null}
import httpx
try:
run = client.invoke_workflow(deployment="my-workflow", variant="default")
except httpx.HTTPStatusError as exc:
print("Fetch Hive returned", exc.response.status_code, exc.response.text)
```
See [Error Handling](./error-handling) for workflow-specific failure cases and [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for HTTP status code meanings.
## Links
* [Package on PyPI](https://pypi.org/project/fetch-hive-sdk/)
* [Source on GitHub](https://github.com/Fetch-Hive/python-sdk)
## Next steps
* [Callback Delivery and Webhook Triggers](./async-and-webhooks) - Verify callback signatures
* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Invoke Workflow](../api-reference/workflows/invoke) - Full endpoint reference
# Run with Ruby SDK
Source: https://docs.fetchhive.com/workflows/run-with-ruby-sdk
Invoke a workflow deployment from Ruby with the fetch_hive gem
Use the official `fetch_hive` gem when you want to invoke a workflow deployment from Ruby. The SDK wraps the public [`POST /v1/workflow/invoke`](../api-reference/workflows/invoke) endpoint, handles authentication, and supports both direct responses and callback delivery.
## Installation
Add to your `Gemfile`:
```ruby theme={null}
gem "fetch_hive"
```
Then run:
```bash theme={null}
bundle install
```
Or install directly:
```bash theme={null}
gem install fetch_hive
```
The gem uses `faraday` under the hood and supports Ruby 3.0+.
## Authentication
Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the client reads it automatically):
```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```
```ruby theme={null}
require "fetch_hive"
client = FetchHive::Client.new
```
Or pass the key explicitly:
```ruby theme={null}
client = FetchHive::Client.new(api_key: "fhk_...")
```
See [API Keys](../workspace/api-keys) for how to create and rotate keys.
## Basic example
Run a workflow deployment directly. The call blocks until the workflow finishes:
```ruby theme={null}
require "fetch_hive"
client = FetchHive::Client.new
run = client.invoke_workflow(
deployment: "YOUR_DEPLOYMENT_NAME",
variant: "YOUR_VARIANT_NAME",
inputs: { topic: "State of enterprise AI in 2026" }
)
puts run["run_status"]
puts run["output"]
```
See the [direct response shape](../api-reference/workflows/invoke#response).
## Method reference
| Keyword | Type | Required | Description |
| -------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `deployment` | `String` | Yes | The workflow deployment name |
| `variant` | `String` | No | The deployment variant name |
| `inputs` | `Hash` | No | Key-value pairs for the variables defined on the **Start** step |
| `async_mode` | `Boolean` | No | When `true`, return immediately and deliver the result by signed callback |
| `callback_url` | `String` | No | Required when `async_mode: true` - the HTTPS callback URL to call when the run finishes |
| `user` | `String` | No | Opaque caller identifier surfaced in [User Tracking](../user-tracking/overview) |
| `metadata` | `Hash` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |
`invoke_workflow` builds the request body for you. When you pass `async_mode: true`, the SDK sends:
```json theme={null}
{
"async": { "enabled": true, "callback_url": "https://example.com/webhook" }
}
```
## Handling the response
```ruby theme={null}
run = client.invoke_workflow(deployment: "my-workflow", variant: "default")
puts run["run_status"] # "completed" | "failed" | "running" | "queued"
puts run["output"] # final workflow output
puts run["request_id"] # use this to look up the run in Logs
```
## Callback delivery
Pass `async_mode: true` to return immediately and have Fetch Hive call your callback URL when the run finishes:
```ruby theme={null}
run = client.invoke_workflow(
deployment: "YOUR_DEPLOYMENT_NAME",
variant: "YOUR_VARIANT_NAME",
inputs: { topic: "State of enterprise AI in 2026" },
async_mode: true,
callback_url: "https://example.com/callback"
)
puts "Queued: #{run['run_status']}"
puts "Webhook secret: #{run['webhook_secret']}"
```
Store the `webhook_secret` so you can verify the signature on the incoming callback. See [Callback Delivery and Webhook Triggers](./async-and-webhooks) for the verification flow and signed payload shape.
## Configuration
| Option | Default | Description |
| ---------- | ------------------------------ | ------------------------------------------------------------------------------- |
| `api_key` | `ENV["FETCH_HIVE_API_KEY"]` | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL |
| `timeout` | `120` | Request timeout in seconds - increase for long-running direct workflow requests |
```ruby theme={null}
client = FetchHive::Client.new(
api_key: "fhk_...",
base_url: "https://api.fetchhive.com/v1",
timeout: 600
)
```
## Errors
Non-2xx responses raise a `RuntimeError` with the status code and body. Rescue them if you need to handle failures:
```ruby theme={null}
begin
run = client.invoke_workflow(deployment: "my-workflow", variant: "default")
rescue => e
warn "Fetch Hive error: #{e.message}"
end
```
See [Error Handling](./error-handling) for workflow-specific failure cases and [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for HTTP status code meanings.
## Links
* [Gem on RubyGems](https://rubygems.org/gems/fetch_hive)
* [Source on GitHub](https://github.com/Fetch-Hive/ruby-sdk)
## Next steps
* [Callback Delivery and Webhook Triggers](./async-and-webhooks) - Verify callback signatures
* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Invoke Workflow](../api-reference/workflows/invoke) - Full endpoint reference
# Scheduled Deployments
Source: https://docs.fetchhive.com/workflows/scheduled-deployments
Run workflow deployment variants automatically from the dashboard with saved inputs
Use schedules when a workflow deployment should run automatically, such as a daily research search or a weekly reporting workflow.
Schedules are managed from the workflow deployment detail page. Open a deployment, click **Schedules**, then create or edit a schedule for one of the deployment variants.
## What a schedule stores
A workflow schedule stores:
* the deployment variant to run
* a schedule name
* active or paused status
* recurrence settings
* timezone
* optional callback URL for signed completion delivery
* saved **Start** input values
The schedule runs the published deployment variant, not the mutable workflow draft. The saved input values are used each time the schedule fires.
When a **Start** input is configured as **Array**, the schedule form stores a native JSON array. Enter the value as valid JSON, such as `["one", "two"]` or `[{"url":"https://example.com"}]`.
## Supported recurrence
The first schedule builder supports:
* every `N` days at a local time
* every `N` weeks on selected weekdays at a local time
Fetch Hive calculates the next run in the schedule timezone. This keeps local run times consistent across accounts and avoids requiring raw cron syntax.
## Scheduled run behavior
Scheduled runs reuse the same execution path as normal workflow deployment invokes. That means:
* the deployment version snapshot stays intact
* workflow step settings, including search language settings, are preserved
* billing and hosted LLM credit checks still apply
* personal credentials and deprecated model checks still apply
* workflow concurrency limits still apply
* optional callback delivery runs when the schedule completes or fails
* runs appear in workflow logs
Scheduled runs include metadata marking them as schedule-triggered, including the schedule id, schedule name, and scheduled time.
They are attributed to the workspace Default API key in workflow logs and include the saved schedule inputs in the request payload and trace details.
If scheduled execution is delayed by downtime or worker recovery, Fetch Hive launches only the latest due occurrence instead of replaying every missed occurrence.
## Pause, resume, and delete
Pause a schedule when it should stop launching new runs without deleting its configuration.
Resume recalculates the next run time from the current time.
Deleting a schedule archives it, so past schedule run history can still be audited internally.
## Notes
Schedules currently apply only to published workflow deployments. Draft workflow scheduling and dynamic date variables for saved inputs are not part of this version.
# Sub-workflow
Source: https://docs.fetchhive.com/workflows/steps/advanced/sub-workflow
Run another workflow from a workflow step
Use **Sub-workflow** when one workflow should hand work to another saved workflow and wait for its result before continuing.
> **Note:** Sub-workflow is not yet available in the workflow editor. Existing workflows that already use this step continue to run; new steps cannot be added from the dashboard until configuration UI ships.
## When to use it
Use a Sub-workflow step to reuse a workflow you already trust, split a large process into smaller workflows, or call the same workflow from multiple parent workflows.
The parent workflow pauses at the Sub-workflow step while the selected workflow runs. When the child workflow completes, the Sub-workflow step stores the child result so later parent steps can reference it.
## Configure the step
Add **Sub-workflow** from the advanced step group.
Choose the workflow to run.
Map parent values into the selected workflow's start inputs. You can use fixed values or variables from earlier parent steps.
Use **When the step fails** to choose whether a failed child workflow should stop the parent workflow or let the parent continue.
## Runtime behavior
The child workflow appears as its own workflow run in logs and remains linked to the parent run.
If the parent run is cancelled while the child workflow is active, Fetch Hive also cancels the child run.
If the child workflow fails, the Sub-workflow step is marked failed. **Terminate Workflow** stops the parent run. **Continue** records the failure on that step and lets later parent steps run.
## Tips
Keep the child workflow's start inputs clear and stable. A Sub-workflow step is easiest to maintain when the parent only maps the values the child workflow actually needs.
Open workflow logs when debugging. The parent run shows where the Sub-workflow step happened, and the linked child run shows the detailed steps inside the child workflow.
See also: [Error Handling](../../error-handling), [Logs](../../logs), and [Creating and Editing](../../creating-and-editing)
# Agent
Source: https://docs.fetchhive.com/workflows/steps/ai/agent
Run a saved agent from a workflow step by selecting the agent and sending it a message
Use **Agent** when you want a workflow step to call one of your existing workspace agents. The step sends a message to that agent. The agent's own instructions, model, and tools apply — those settings stay on the agent, not on the step.
This is different from **AI Prompt**, which configures a one-off LLM call on the step itself.
## Configuration
| Option | Required | Description |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Agent | Yes | The saved workspace agent to run. Open the agent editor from the step settings to change the agent's instructions, model, or tools. |
| Message | Yes | The message sent to the agent. Supports workflow variables such as `{{step_1.output}}`. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
Pick an agent from the searchable list. Only active workspace agents appear. After you select one, the settings sheet shows a short summary (model and tool count) and a link to edit the agent.
Write the message the agent should receive. Use **Insert Variable** to pass earlier step output into the message.
Credits for this step are charged on the agent run itself, not as a separate workflow-step fee.
## Output
This step stores the agent's reply as the step output.
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
For example, if this is `step_2`:
```text theme={null}
{{step_2.output}}
```
Later steps can insert that text with the variable picker.
## Example
Add **Agent** from the workflow step picker.
Select a support or research agent you already configured.
Set **Message** to something like:
```text theme={null}
Summarize this for a customer: {{step_1.output}}
```
Click **Run** in the step header to test. The agent's reply appears in **Output**, and later steps can reference it.
## See also
* [AI Prompt](./ai-prompt)
* [Creating and Editing](../../creating-and-editing)
* [Testing and Iteration](../../testing-and-iteration)
* [Error Handling](../../error-handling)
# AI Prompt
Source: https://docs.fetchhive.com/workflows/steps/ai/ai-prompt
Configure a workflow step that runs an LLM prompt with messages and returns text or structured output
Use **AI Prompt** when you want a workflow step to send a prompt to an LLM and store the assistant response for later steps.
## Configuration
| Option | Required | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Charge Type | No | Whether the step uses **Hosted** or **Personal** model billing. |
| LLM Model | Yes | The model selected in **LLM Model**. |
| Temperature | No | Controls how predictable or creative the response is when the selected model uses temperature. |
| Max Thinking Tokens | No | Sets **Max Thinking Tokens** for manual-budget Anthropic Claude and Google Gemini thinking models. Controls how many tokens the model may use for internal reasoning before producing a response. |
| Reasoning Effort | No | Sets **Reasoning Effort** (low, medium, or high) for OpenAI and xAI reasoning models. |
| Reasoning | No | Toggles reasoning on or off for supported third-party reasoning models such as Cohere. |
| Max Tokens | No | Sets the maximum response length for the step. |
| Prompt | Yes | Prompt messages in the **Prompt** section. Each message has a role and content. |
| Response Format | No | Lets you switch **JSON Schema** on for supported providers. |
| JSON Schema | No | Structured response schema used when **JSON Schema** is enabled. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
| The **AI Prompt** step uses a wider settings sheet than the other workflow step types. The left side holds the prompt configuration, and the right side shows prompt messages and model responses from test runs in the same view. | | |
In **Parameters**, the exact controls change with the selected model:
* **Temperature** is shown for standard models.
* **Max Thinking Tokens** is shown for manual-budget Anthropic Claude and Google Gemini thinking models.
* **Reasoning Effort** is shown for adaptive Claude models such as Claude Sonnet 4.6+, Claude Opus 4.6+, Claude Opus 5, and Claude Fable 5.
* **Reasoning Effort** is shown for OpenAI and xAI reasoning models (low / medium / high).
* **Reasoning** (enabled/disabled) is shown for supported third-party reasoning models such as Cohere.
In **Prompt**, click **Add Message** to build the message list. The first new message is a `system` message. After that, new messages default to `user`. Each message supports variable insertion from the workflow with the **Insert Variable** button. For vision-capable models, `user` messages can also include an image URL.
If your selected provider supports structured output, you can enable **JSON Schema** in **Response Format**. This opens a schema editor where you can set a schema name, load an example, and save the JSON schema the model must follow.
`assistant` is available as a message role in the editor, but this step still runs as a single prompt execution and stores the final assistant response as the step output.
## Output
This step stores the final assistant response as the step output.
Use the variable picker to insert the exact reference path for a previous prompt step. In templates and later steps, the base reference is:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
If the response is plain text, reference the full value directly:
```text theme={null}
{{step_2.output}}
```
If **JSON Schema** is enabled and the model returns a structured object, you can reference nested fields:
```text theme={null}
{{step_2.output.title}}
{{step_2.output.summary}}
```
The exact available keys depend on the schema and model response shown in the variable picker.
## Example
Add **AI Prompt** from the workflow step picker.
Set **Name** to something like `Summarize article`.
In **Parameters**, choose your **Charge Type** and **LLM Model**. Adjust **Temperature**, **Reasoning Effort**, **Max Thinking Tokens**, or the **Reasoning** toggle if those controls are shown for your model.
In **Prompt**, add a `system` message that explains the task and a `user` message that inserts earlier workflow data such as `{{step_1.output}}`.
If you need structured output, enable **JSON Schema** and define fields such as `title` and `summary`.
Click **Run** in the step header to test the step. The response appears in the right-hand panel, and later steps can reference that output with the variable picker.
## Notes
* Use the step identifier shown in the variable picker when you reference this step in later fields.
* The **Clear** action removes previous model responses from the test panel. It does not remove your prompt messages.
* The step output is the final assistant response, not the full request metadata.
* When **JSON Schema** is enabled, later steps can reference the returned object by field instead of parsing raw text.
* When the workflow copilot adds or edits an AI Prompt step for you, it writes three messages: a `system` message (objective, edge cases, staying on task), a `user` message with Instructions/Steps/Output Format/Examples/Notes sections, and — only when the step takes input from an earlier step or a workflow variable — a final `user` message holding just the variable placeholders (like `{{step_1.output}}`). Keeping placeholders in that last message keeps the rest of the prompt unchanged between runs, which helps Fetch Hive reuse the unchanged part of the prompt for models that support prompt caching.
See also: [Creating and Editing](../../creating-and-editing), [Testing and Iteration](../../testing-and-iteration), and [Use your own API Key](../../../workspace/llm-providers)
# Google AI Mode
Source: https://docs.fetchhive.com/workflows/steps/ai/google-ai-mode
Configure a workflow step that runs a Google AI Mode search and stores the returned result for later steps
Use **Google AI Mode** when you want a workflow step to run a Google AI Mode search and reuse that result elsewhere in your workflow.
## Configuration
| Option | Required | Description |
| ------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Search Query | Yes | The value entered in **Search Query**. |
| Charge Type | No | Whether the step uses **Hosted** or **Personal** billing. |
| Language | No | Language code used for the query. You can choose a preset language or enter a custom value. |
| Language Custom Value | No | Turns **Custom Value** on for **Language**. |
| Location | No | Location used for the query. You can choose a preset location or enter a custom value. |
| Location Custom Value | No | Turns **Custom Value** on for **Location**. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
| This step uses the standard **Settings** and **Output** tab layout. | | |
Use the **Insert Variable** button next to **Search Query**, **Language**, and **Location** when those values should come from start inputs or earlier step output.
For **Language** and **Location**, **Custom Value** changes the control from a selectable list into a freeform field.
To inspect supported countries programmatically, use [Search Service Countries](../../../api-reference/overview). Google AI Mode uses country-name values such as `United States`.
## Output
This step stores the returned Google AI Mode result as the step output.
When **Parallelization** is enabled, each version runs at the same time and the step output becomes an ordered array with one entry per successful version.
Use the base output reference in later steps:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
If the response contains object fields, you can reference them with nested paths:
```text theme={null}
{{step_2.output.some_field}}
```
The exact fields depend on the returned result, so inspect the **Output** tab or the variable picker before you rely on nested references.
## Example
Add **Google AI Mode** to your workflow.
Set **Search Query** to the topic you want to research.
Choose **Hosted** or **Personal** in the model type field, then set **Language** and **Location** from the presets or with **Custom Value** enabled.
To compare multiple query, language, or location versions, enable **Parallelization** and configure each version's overrides.
Click **Run** in the step header, then review the result in **Output** before passing that data into another step.
## Notes
* **Google AI Mode** is a separate step from **Google AI Overview** and has its own settings page.
* The visible difference in this editor is the **Hosted** or **Personal** billing option in the settings form.
* Use the variable picker to insert nested output paths after you have a real result to inspect.
See also: [Creating and Editing](../../creating-and-editing) and [Testing and Iteration](../../testing-and-iteration)
# Google AI Overview
Source: https://docs.fetchhive.com/workflows/steps/ai/google-ai-overview
Configure a workflow step that retrieves Google's AI Overview result for a search query
Use **Google AI Overview** when you want a workflow step to fetch Google's AI Overview result for a query and pass that response into later steps.
## Configuration
| Option | Required | Description |
| --------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Search Query | Yes | The value entered in **Search Query**. |
| Language | No | Language code used for the query. You can choose a preset language or enter a custom value. |
| Language Custom Value | No | Turns **Custom Value** on for **Language**. |
| Location | No | Location used for the query. You can choose a preset location or enter a custom value. |
| Location Custom Value | No | Turns **Custom Value** on for **Location**. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
| The **Settings** tab holds the search configuration, and the **Output** tab shows the latest test result. | | |
Use the **Insert Variable** button next to **Search Query**, **Language**, or **Location** when you want those values to come from earlier workflow steps or start inputs.
For both **Language** and **Location**, you can work in two modes:
* With **Custom Value** off, Fetch Hive shows a selectable list.
* With **Custom Value** on, Fetch Hive switches that field to a freeform text input.
To inspect supported countries programmatically, use [Search Service Countries](../../../api-reference/overview). Google AI Overview uses alpha-2 country values such as `US`.
## Output
This step stores the returned AI Overview payload as the step output.
When **Parallelization** is enabled, each version runs at the same time and the step output becomes an ordered array with one entry per successful version.
Use the base output reference in later steps:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
If the returned output is an object, you can reference fields from the variable picker with dot paths such as:
```text theme={null}
{{step_2.output.some_field}}
```
Because the exact response shape depends on the Google AI Overview result for your query, use the variable picker or the **Output** tab to confirm the available keys for your workflow.
## Example
Add **Google AI Overview** to your workflow.
Set **Search Query** to something like `latest AI chip announcements`.
Choose a preset **Language** and **Location**, or enable **Custom Value** if those should be filled from workflow variables.
To compare multiple query, language, or location versions, enable **Parallelization** and configure each version's overrides.
Click **Run** in the step header to test the step, then open **Output** to inspect the response before wiring it into later steps.
## Notes
* This step is configured in the standard **Settings** and **Output** tab layout, not the wide split-pane used by **AI Prompt**.
* The output shape depends on the result returned for the query, so check the live output before referencing nested fields in later steps.
* Use the variable picker to insert output paths instead of typing them manually when you want to avoid path mistakes.
See also: [Creating and Editing](../../creating-and-editing) and [Testing and Iteration](../../testing-and-iteration)
# Image Generation
Source: https://docs.fetchhive.com/workflows/steps/ai/image-generation
Configure a workflow step that generates one or more images and returns uploaded asset records for later steps
Use **Image Generation** when you want a workflow step to create images from a prompt and reuse the generated assets later in the workflow.
Supports **OpenAI** (`gpt-image-2`), **xAI Grok Imagine** (`grok-imagine-image-quality`, `grok-imagine-image-2.0`, `grok-imagine-image`), and hosted **Google Gemini** (`gemini-2.5-flash-image`, `gemini-3.1-flash-lite-image`, `gemini-3.1-flash-image`, `gemini-3-pro-image`). Select the model in the **Model** dropdown at the top of the settings form. OpenAI-specific options (Size, Quality, Background, Moderation, Output Format, Output Compression) are hidden when a Grok or Gemini model is selected. Gemini shows aspect-ratio choices instead of OpenAI size tiles. Gemini 3 image models also expose a **Resolution** selector (`0.5K`, `1K`, `2K`, `4K` depending on model).
## Configuration
| Option | Required | Description |
| ------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Model | No | Image model to use. Default: `gpt-image-2`. |
| Prompt | Yes | The text entered in **Prompt**. |
| Image Size / Aspect Ratio | No | OpenAI uses size tiles. Gemini uses aspect ratios such as `1:1`, `16:9`, or `9:16`. |
| Image Resolution | No | Gemini 3 image models only. `1K` default; `gemini-3.1-flash-image` also supports `0.5K`, `2K`, and `4K`. |
| Image Count | No | Number of images to generate. |
| Image Quality | No | Quality level for the generated images (OpenAI only). |
| Image Background | No | Background mode for the image output (OpenAI only). |
| Image Moderation | No | Moderation setting for the generation request (OpenAI only). |
| Output Format | No | Output file format (OpenAI only). |
| Output Compression | No | Compression level for formats that support it (OpenAI only). |
| Charge Type | No | Whether the step uses **Hosted** or **Personal** billing. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
Use the **Insert Variable** button next to **Prompt** when part of the image description should come from workflow inputs or earlier steps.
This step uses **Settings** and **Output** tabs. The **Output** tab shows the generated images as a gallery after a successful test run.
## Output
This step outputs an object with:
* `settings`: the selected model plus provider-specific image generation settings used for the call
* `assets`: an array of generated asset records
Each asset item includes uploaded asset data such as:
* `id`
* `file_url`
* `file_name`
* `file_size`
* `file_type`
Use the base output reference to pass the full object forward:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
To reference a specific generated image field, use an indexed path such as:
```text theme={null}
{{step_2.output.assets.0.file_url}}
{{step_2.output.assets.0.file_name}}
```
To reference settings used by the step:
```text theme={null}
{{step_2.output.settings.model}}
{{step_2.output.settings.image_size}}
```
The exact settings keys depend on the selected provider. OpenAI outputs include OpenAI-specific fields such as `image_quality`, `image_background`, `image_output_format`, and `image_output_compression`. Gemini outputs include the selected aspect ratio in `image_size`. xAI outputs include the model, provider, and image count.
Use the variable picker after a test run to confirm the exact path you want to insert.
## Example
Add **Image Generation** to your workflow.
Write a detailed **Prompt** such as `Create a product hero image for a blue insulated water bottle on a clean studio background`.
Choose a **Size** or **Aspect Ratio**, set **Image Count**, then adjust the provider-specific options that are visible.
If you want smaller JPEG or WebP output, lower **Output Compression**. If you keep **Output Format** set to **PNG**, that compression control stays disabled.
Click **Run** in the step header. After the run finishes, open **Output** to review the returned images and use the variable picker to reference the generated asset fields in later steps.
## Notes
* If **Output Format** is **JPEG**, **Transparent** is not available in **Background** (OpenAI only).
* If **Output Format** is **PNG**, **Output Compression** is disabled in the editor (OpenAI only).
* When using a Grok Imagine model, images are always returned as PNG regardless of the Output Format setting.
* Gemini image generation is hosted-only in this workflow step. Personal/BYOK Gemini image generation is not supported in v1.
* xAI Grok Imagine is billed at a fixed rate per image (not per token). OpenAI `gpt-image-2` is billed per token. Gemini is billed from input tokens plus generated-image output tokens.
* This step returns uploaded asset records, not just raw image bytes.
* Before the image provider is called, Fetch Hive checks whether your account has reached its plan storage limit. If the limit is reached, the step fails without generating or uploading new images.
* Generated file URLs are useful when a later step needs to pass an image reference forward.
See also: [Creating and Editing](../../creating-and-editing) and [Testing and Iteration](../../testing-and-iteration)
# Airtable
Source: https://docs.fetchhive.com/workflows/steps/integrations/airtable
Configure a workflow step that reads or writes Airtable records using a connected Airtable account
Use **Airtable** when you want a workflow step to create, list, update, or retrieve records in an Airtable base from a connected account.
## Configuration
| Option | Required | Description |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Authentication | Yes | The connected Airtable account to use for this step. |
| Action | Yes | The Airtable action to perform (Create Record, List Records, Update Record, Get Record). |
| Arguments | Yes | Per-action form fields generated from the action's schema. Each text field has an **Insert Variable** button for injecting `{{placeholder}}` values. A **Raw JSON** tab is available for advanced usage. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
Before you configure this step, connect Airtable in **Integrations** for your workspace using the OAuth flow. If no active Airtable connection is available, the step shows a warning with a link to **Integrations** instead of the account selector.
## Arguments form
When you select an action, the **Arguments** section automatically renders a form driven by the action's input schema — no manual JSON editing required. Each field includes:
* A label and description from the action's schema.
* An **Insert Variable** button next to the label that injects references like `{{step_1.output.id}}` at the cursor position.
* Validation feedback inline if a required field is left empty.
### Field types
| Field type | How it renders | Insert Variable available |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Text / number | Plain input. | Create Record and Update Record only |
| Boolean | Toggle switch (label on the left, switch on the right). | No |
| Base ID (`baseId`) | Dropdown populated from your connected Airtable account — select your base by name. Use **Enter custom value** for a base ID or `{{variable}}`. | Manual entry only |
| Record ID (`recordId`) | Dropdown populated after **Base ID** and **Table ID or Name** are set — lists records from that table. | Manual entry only |
| Fields | A JSON textarea (mono font). Paste a raw JSON object or use **Insert Variable** to pass a `{{step_1.record}}` placeholder when the fields come from a previous step's output. | Always |
| Records (`records`) | A JSON textarea on **Create Records** and **Update Multiple Records**. Paste a JSON array (for example `[{"fields":{"Name":"Alice"}}]`) or use **Insert Variable** to pass output from a previous step such as `{{data_transform.output}}`. | Always |
| Tag list / array | List of text inputs. The **Add** button appears next to the array label. | No (array items do not support variable insertion) |
Switch to the **Raw JSON** tab for power users or when you prefer to write the full arguments object by hand. Changes in either tab stay in sync.
## Actions
| Action | Description |
| ------------- | -------------------------------------------------- |
| Create Record | Create a new record in a specified table. |
| List Records | List records from a table with optional filtering. |
| Update Record | Modify an existing record by ID. |
| Get Record | Retrieve a single record by ID. |
## Output
This step stores the Airtable API response as the step output. The shape of the response depends on the action.
Use the full output reference in later steps:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
For example, after a **Create Record** step you might reference the new record's ID:
```text theme={null}
{{step_2.output.id}}
```
## Example
1. Open **Integrations** and connect Airtable if you have not already done that.
2. Add an **Airtable** step to your workflow.
3. Select a connected account in **Authentication**.
4. Choose **Create Record** in **Action**.
5. In the **Arguments** form, fill in **Table ID** and the field values. Use **Insert Variable** to reference an earlier step's output for any field value.
6. Click **Run** in the step header to test the action, then review the returned payload in **Output**.
## Notes
* This step depends on a connected Airtable integration in your workspace.
* The **Raw JSON** tab in Arguments is always available if you prefer to write JSON directly.
* The `tableId` is the Airtable table identifier (starts with `tbl`).
## Using Airtable as an Agent Tool
You can also add Airtable as a tool in the **Agent Editor**. Open the agent, click **Add tool**, and select **Airtable**. In the tool settings panel, choose the connected Airtable account the agent should use. The agent will call Airtable actions automatically during conversations when relevant.
See also: [Integrations](../../../workspace/integrations), [Creating and Editing](../../creating-and-editing), and [Testing and Iteration](../../testing-and-iteration)
# Google Docs
Source: https://docs.fetchhive.com/workflows/steps/integrations/google-docs
Configure a workflow step that creates, copies, searches, and updates Google Docs using a connected account
Use **Google Docs** when you want a workflow step to create a document, copy an existing file, search documents, or insert text in a connected account.
## Configuration
| Option | Required | Description |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Authentication | Yes | The connected Google Docs account to use for this step. |
| Action | Yes | The Google Docs action to perform (for example Create Document, Search Documents, Insert Text). |
| Arguments | Yes | Per-action form fields generated from the action's schema. Each text field has an **Insert Variable** button for injecting `{{placeholder}}` values. A **Raw JSON** tab is available for advanced usage. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
Before you configure this step, connect Google Docs in **Integrations** for your workspace using the OAuth flow. If no active connection is available, the step shows a warning with a link to **Integrations** instead of the account selector.
## Arguments form
When you select an action, the **Arguments** section automatically renders a form driven by the action's input schema. Each field includes:
* A label and description from the action's schema.
* An **Insert Variable** button next to eligible fields that injects references like `{{step_1.output.id}}` at the cursor position.
* Validation feedback inline if a required field is left empty.
Switch to the **Raw JSON** tab for power users or when you prefer to write the full arguments object by hand. Changes in either tab stay in sync.
## Common actions
| Action | Description |
| ----------------------------- | -------------------------------------------- |
| Create Document | Create a new document with a title and text. |
| Create Document from Markdown | Create a document from markdown content. |
| Copy Document | Duplicate an existing document. |
| Search Documents | Find documents in the connected account. |
| Get Document | Retrieve a document by ID. |
| Insert Text | Insert text into an existing document. |
Destructive actions such as deleting content ranges, headers, or tables are not exposed in the workflow action picker.
## Output
This step stores the Google Docs API response as the step output. The shape of the response depends on the action.
Use the full output reference in later steps:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
For example, after a **Create Document** step you might reference the returned document ID:
```text theme={null}
{{step_2.output.documentId}}
```
Use the variable picker after a test run to confirm the exact keys available in your workflow.
## Example
1. Open **Integrations** and connect Google Docs if you have not already done that.
2. Add a **Google Docs** step to your workflow.
3. Select a connected account in **Authentication**.
4. Choose **Create Document** in **Action**.
5. In the **Arguments** form, fill in the title and text. Use **Insert Variable** to reference an earlier step's output for any field value.
6. Click **Run** in the step header to test the action, then review the returned payload in **Output**.
## Notes
* This step depends on a connected Google Docs integration in your workspace.
* The workflow action picker shows a curated subset of document actions. Agents with the Google Docs tool can access additional safe actions.
* OAuth may show third-party authorization branding during the connect flow.
* If a previous connection stops working, reconnect Google Docs in **Integrations**, then select the new account in **Authentication**.
## Using Google Docs as an Agent Tool
You can also add Google Docs as a tool in the **Agent Editor**. Open the agent, click **Add tool**, and select **Google Docs**. In the tool settings panel, choose the connected account the agent should use. The agent will call Google Docs actions automatically during conversations when relevant.
See also: [Integrations](../../../workspace/integrations), [Creating and Editing](../../creating-and-editing), and [Testing and Iteration](../../testing-and-iteration)
# Google Maps
Source: https://docs.fetchhive.com/workflows/steps/integrations/google-maps
Configure a workflow step that geocodes addresses, searches places, and calculates routes using a connected account
Use **Google Maps** when you want a workflow step to geocode addresses, search for places, retrieve place details, calculate routes, or look up time zones from a connected account.
## Configuration
| Option | Required | Description |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Authentication | Yes | The connected Google Maps account to use for this step. |
| Action | Yes | The maps action to perform (for example Text Search, Geocoding API, Get Route). |
| Arguments | Yes | Per-action form fields generated from the action's schema. Each text field has an **Insert Variable** button for injecting `{{placeholder}}` values. A **Raw JSON** tab is available for advanced usage. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
Before you configure this step, connect Google Maps in **Integrations** for your workspace using the OAuth flow. If no active connection is available, the step shows a warning with a link to **Integrations** instead of the account selector.
## Arguments form
When you select an action, the **Arguments** section automatically renders a form driven by the action's input schema. Text and query fields support workflow placeholders via **Insert Variable**.
Switch to the **Raw JSON** tab for power users or when you prefer to write the full arguments object by hand. Changes in either tab stay in sync.
## Available actions
The workflow action picker shows a curated subset focused on location lookups and routing:
| Action | Description |
| -------------------------- | ----------------------------------------------------------------------- |
| Text Search | Find places using a free-text query. |
| Nearby Search | Search for places within a circular area. |
| Get Place Details | Retrieve details for a place by ID. |
| Autocomplete | Return place predictions for partial text input. |
| Geocoding API | Convert addresses to coordinates or reverse-geocode coordinates. |
| Geocode Address | Geocode a single address string. |
| Geocode Address With Query | Geocode using the modern query-parameter API. |
| Reverse Geocode Location | Convert coordinates to a human-readable address. |
| Geocode Place | Resolve a place ID to coordinates. |
| Get Route | Calculate a route with distance and duration. |
| Get Direction | Retrieve turn-by-turn directions between two points. |
| Compute Route Matrix | Calculate distances and times across multiple origins and destinations. |
| Distance Matrix (Legacy) | Legacy distance/time matrix between origins and destinations. |
| Get Time Zone | Look up the time zone for a location. |
| Embed Google Map | Generate an embeddable map URL or iframe snippet. |
Tile, aerial video, and device geolocation actions are not exposed in the workflow action picker.
## Output
This step stores the Google Maps API response as the step output. The shape of the response depends on the action.
Use the full output reference in later steps:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
## Example
1. Open **Integrations** and connect Google Maps if you have not already done that.
2. Add a **Google Maps** step to your workflow.
3. Select a connected account in **Authentication**.
4. Choose **Text Search** in **Action** and enter a query such as `coffee shops in Austin, TX`.
5. Pass coordinates or place IDs from **Output** into a later **Get Route** step.
6. Click **Run** in the step header to test the action.
## Notes
* This step depends on a connected Google Maps integration in your workspace.
* Google Maps API quotas and billing apply to workflow actions the same as direct API usage.
* OAuth may show third-party authorization branding during the connect flow.
## Using Google Maps as an Agent Tool
You can also add Google Maps as a tool in the **Agent Editor**. Open the agent, click **Add tool**, and select **Google Maps**. In the tool settings panel, choose the connected account the agent should use.
See also: [Integrations](../../../workspace/integrations), [Creating and Editing](../../creating-and-editing), and [Testing and Iteration](../../testing-and-iteration)
# Google Sheets
Source: https://docs.fetchhive.com/workflows/steps/integrations/google-sheets
Configure a workflow step that creates, reads, searches, and updates Google Sheets using a connected account
Use **Google Sheets** when you want a workflow step to create a spreadsheet, search existing files, read sheet data, or append and update values in a connected account.
## Configuration
| Option | Required | Description |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Authentication | Yes | The connected Google Sheets account to use for this step. |
| Action | Yes | The Google Sheets action to perform (for example Create Spreadsheet, Search Spreadsheets, Append Values). |
| Arguments | Yes | Per-action form fields generated from the action's schema. Each text field has an **Insert Variable** button for injecting `{{placeholder}}` values. A **Raw JSON** tab is available for advanced usage. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
Before you configure this step, connect Google Sheets in **Integrations** for your workspace using the OAuth flow. If no active connection is available, the step shows a warning with a link to **Integrations** instead of the account selector.
## Arguments form
When you select an action, the **Arguments** section automatically renders a form driven by the action's input schema. Each field includes:
* A label and description from the action's schema.
* An **Insert Variable** button next to eligible fields that injects references like `{{step_1.output.id}}` at the cursor position.
* Validation feedback inline if a required field is left empty.
Switch to the **Raw JSON** tab for power users or when you prefer to write the full arguments object by hand. Changes in either tab stay in sync.
## Common actions
| Action | Description |
| -------------------- | ------------------------------------------- |
| Create Spreadsheet | Create a new spreadsheet with a title. |
| Search Spreadsheets | Find spreadsheets in the connected account. |
| Get Spreadsheet Info | Retrieve metadata for a spreadsheet by ID. |
| Get Sheet Names | List worksheet names in a spreadsheet. |
| Batch Get | Read values from one or more ranges. |
| Append Values | Append rows to a sheet. |
| Update Values | Write values to a range. |
Destructive actions such as clearing ranges or deleting sheets are not exposed in the workflow action picker.
## Output
This step stores the Google Sheets API response as the step output. The shape of the response depends on the action.
Use the full output reference in later steps:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
For example, after a **Create Spreadsheet** step you might reference the returned spreadsheet ID:
```text theme={null}
{{step_2.output.spreadsheetId}}
```
Use the variable picker after a test run to confirm the exact keys available in your workflow.
## Example
1. Open **Integrations** and connect Google Sheets if you have not already done that.
2. Add a **Google Sheets** step to your workflow.
3. Select a connected account in **Authentication**.
4. Choose **Create Spreadsheet** in **Action**.
5. In the **Arguments** form, fill in the title. Use **Insert Variable** to reference an earlier step's output for any field value.
6. Click **Run** in the step header to test the action, then review the returned payload in **Output**.
To write rows after creating a spreadsheet, add a second Google Sheets step that uses **Append Values** or **Update Values** and pass the spreadsheet ID from the create step.
## Notes
* This step depends on a connected Google Sheets integration in your workspace.
* The workflow action picker shows a curated subset of spreadsheet actions. Agents with the Google Sheets tool can access additional safe actions.
* OAuth may show third-party authorization branding during the connect flow.
* If a previous connection stops working, reconnect Google Sheets in **Integrations**, then select the new account in **Authentication**.
## Using Google Sheets as an Agent Tool
You can also add Google Sheets as a tool in the **Agent Editor**. Open the agent, click **Add tool**, and select **Google Sheets**. In the tool settings panel, choose the connected account the agent should use. The agent will call Google Sheets actions automatically during conversations when relevant.
See also: [Integrations](../../../workspace/integrations), [Creating and Editing](../../creating-and-editing), and [Testing and Iteration](../../testing-and-iteration)
# Google Analytics
Source: https://docs.fetchhive.com/workflows/steps/integrations/google_analytics
Configure a workflow step that queries GA4 reports and property metadata using a connected account
Use **Google Analytics** when you want a workflow step to fetch GA4 property metadata, validate dimension/metric combinations, or list accounts and properties from a connected account.
## Configuration
| Option | Required | Description |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Authentication | Yes | The connected Google Analytics account to use for this step. |
| Action | Yes | The analytics action to perform (for example Get Metadata, Check Compatibility, List Account Summaries). |
| Arguments | Yes | Per-action form fields generated from the action's schema. Each text field has an **Insert Variable** button for injecting `{{placeholder}}` values. A **Raw JSON** tab is available for advanced usage. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
Before you configure this step, connect Google Analytics in **Integrations** for your workspace using the OAuth flow. If no active connection is available, the step shows a warning with a link to **Integrations** instead of the account selector.
## Arguments form
When you select an action, the **Arguments** section automatically renders a form driven by the action's input schema. Property fields include a resource picker populated from your connected account.
Switch to the **Raw JSON** tab for power users or when you prefer to write the full arguments object by hand. Changes in either tab stay in sync.
## Available actions
The workflow action picker shows a curated read-only subset:
| Action | Description |
| ---------------------- | ------------------------------------------------------------------ |
| Get Metadata | Discover valid dimensions and metrics for a property. |
| Check Compatibility | Validate dimension and metric combinations before running reports. |
| List Account Summaries | List accounts and child properties. |
| List Property | List properties matching a filter expression. |
| Get Property | Retrieve details for a single property. |
Report actions (Run Report, Run Realtime Report, and Batch Run Reports) are not currently exposed in the workflow action picker.
Advanced optional filter fields (`metricFilter`, `dimensionFilter`) are hidden from the form UI for **Check Compatibility**; use the **Raw JSON** tab if you need them.
Write and admin actions (creating audiences, updating properties, sending events, and similar) are not exposed in the workflow action picker.
## Output
This step stores the Google Analytics API response as the step output. The shape of the response depends on the action.
Use the full output reference in later steps:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
## Example
1. Open **Integrations** and connect Google Analytics if you have not already done that.
2. Add a **Google Analytics** step to your workflow.
3. Select a connected account in **Authentication**.
4. Choose **List Account Summaries** in **Action**.
5. Review the returned accounts and properties in **Output**, or switch to **Get Metadata** / **Get Property** for a specific property.
6. Click **Run** in the step header to test the action.
## Notes
* This step depends on a connected Google Analytics integration in your workspace.
* Use **Get Metadata** or **Check Compatibility** when building complex reports to avoid invalid dimension/metric combinations.
* OAuth may show third-party authorization branding during the connect flow.
## Using Google Analytics as an Agent Tool
You can also add Google Analytics as a tool in the **Agent Editor**. Open the agent, click **Add tool**, and select **Google Analytics**. In the tool settings panel, choose the connected account the agent should use.
See also: [Integrations](../../../workspace/integrations), [Creating and Editing](../../creating-and-editing), and [Testing and Iteration](../../testing-and-iteration)
# Google Calendar
Source: https://docs.fetchhive.com/workflows/steps/integrations/googlecalendar
Configure a workflow step that creates, lists, finds, and updates Google Calendar events using a connected account
Use **Google Calendar** when you want a workflow step to create events, list upcoming meetings, find events, or update calendar entries from a connected account.
## Configuration
| Option | Required | Description |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Authentication | Yes | The connected Google Calendar account to use for this step. |
| Action | Yes | The calendar action to perform (for example Create Event, List Events, Find Event, Update Event). |
| Arguments | Yes | Per-action form fields generated from the action's schema. Each text field has an **Insert Variable** button for injecting `{{placeholder}}` values. A **Raw JSON** tab is available for advanced usage. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
Before you configure this step, connect Google Calendar in **Integrations** for your workspace using the OAuth flow. If no active connection is available, the step shows a warning with a link to **Integrations** instead of the account selector.
## Arguments form
When you select an action, the **Arguments** section automatically renders a form driven by the action's input schema. Each field includes:
* A label and description from the action's schema.
* An **Insert Variable** button next to eligible fields that injects references like `{{step_1.output.id}}` at the cursor position.
* Validation feedback inline if a required field is left empty.
Switch to the **Raw JSON** tab for power users or when you prefer to write the full arguments object by hand. Changes in either tab stay in sync.
## Common actions
| Action | Description |
| ------------------------------ | ---------------------------------------------------------------------- |
| Create Event | Create a new calendar event with title, time, attendees, and location. |
| List Events from All Calendars | List upcoming events across calendars. |
| Find Event | Search for an event by criteria such as time range or text. |
| Get Event | Retrieve a single event by ID. |
| Update Event | Modify an existing event. |
| Free Busy Query | Check availability across calendars for scheduling. |
Destructive actions such as deleting calendars or events are not exposed in the workflow action picker.
## Output
This step stores the Google Calendar API response as the step output. The shape of the response depends on the action.
Use the full output reference in later steps:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
For example, after a **Create Event** step you might reference the new event ID:
```text theme={null}
{{step_2.output.id}}
```
## Example
1. Open **Integrations** and connect Google Calendar if you have not already done that.
2. Add a **Google Calendar** step to your workflow.
3. Select a connected account in **Authentication**.
4. Choose **Create Event** in **Action**.
5. In the **Arguments** form, fill in the event title, start time, and end time. Use **Insert Variable** to reference an earlier step's output for any field value.
6. Click **Run** in the step header to test the action, then review the returned payload in **Output**.
## Notes
* This step depends on a connected Google Calendar integration in your workspace.
* The workflow action picker shows a curated subset of calendar actions. Agents with the Google Calendar tool can access the full toolkit.
* OAuth may show third-party authorization branding during the connect flow.
## Using Google Calendar as an Agent Tool
You can also add Google Calendar as a tool in the **Agent Editor**. Open the agent, click **Add tool**, and select **Google Calendar**. In the tool settings panel, choose the connected account the agent should use. The agent will call calendar actions automatically during conversations when relevant.
See also: [Integrations](../../../workspace/integrations), [Creating and Editing](../../creating-and-editing), and [Testing and Iteration](../../testing-and-iteration)
# Linear
Source: https://docs.fetchhive.com/workflows/steps/integrations/linear
Configure a workflow step that creates or queries Linear issues and teams using a connected Linear account
Use **Linear** when you want a workflow step to create issues, list issues, update issues, or retrieve team information from a connected Linear workspace.
## Configuration
| Option | Required | Description |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Authentication | Yes | The connected Linear account to use for this step. |
| Action | Yes | The Linear action to perform (Create Issue, List Issues, Update Issue, List Teams). |
| Arguments | Yes | Per-action form fields generated from the action's schema. Each text field has an **Insert Variable** button for injecting `{{placeholder}}` values. A **Raw JSON** tab is available for advanced usage. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
Before you configure this step, connect Linear in **Integrations** for your workspace. If no active Linear connection is available, the step shows a warning with a link to **Integrations** instead of the account selector.
## Arguments form
When you select an action, the **Arguments** section automatically renders a form driven by the action's input schema — no manual JSON editing required. Each field includes:
* A label and description from the action's schema.
* An **Insert Variable** button next to the label that injects references like `{{step_1.output.id}}` at the cursor position.
* Validation feedback inline if a required field is left empty.
### Field types
| Field type | How it renders | Insert Variable available |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Text / number | Plain input. | Create Issue and Update Issue only |
| Boolean | Toggle switch (label on the left, switch on the right). | No |
| Team (`team_id` or `teamId`) | Dropdown populated from your connected Linear workspace — select your team by name. Use **Enter custom value** (or manual entry when the list is empty) to type a team UUID or `{{variable}}`. Field name matches the action schema (`team_id` for Create Issue; `teamId` for Update Issue). | Manual entry only |
| Project (`project_id` or `projectId`) | Dropdown populated from your connected Linear workspace — select your project by name. Use **Enter custom value** for a project UUID or `{{variable}}`. | Manual entry only |
| Issue (`issue_id`, `issueId`, or `parentId`) | Dropdown populated from your connected Linear workspace — select an issue by title. | Manual entry only |
| Project update (`id`) | Dropdown populated from project updates in your workspace — select by update body text. | Manual entry only |
| Label IDs / string arrays | List of text inputs. The **Add** button appears next to the array label. | No (array items do not support variable insertion) |
All dropdown options are fetched in a single request when you select a connected account, so opening the settings panel does not trigger multiple API calls. If the lookup fails for a specific field, it falls back to a plain text input so you can still enter a value manually or use a `{{variable}}`.
Switch to the **Raw JSON** tab for power users or when you prefer to write the full arguments object by hand. Changes in either tab stay in sync.
## Actions
| Action | Description |
| ------------ | ------------------------------------------------- |
| Create Issue | Create a new issue in a specified team. |
| List Issues | Search or list issues with optional filters. |
| Update Issue | Modify an existing issue by ID. |
| List Teams | List all teams in the connected Linear workspace. |
## Output
This step stores the Linear API response as the step output. The shape of the response depends on the action.
Use the full output reference in later steps:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
For example, after a **Create Issue** step you might reference the new issue's ID:
```text theme={null}
{{step_3.output.id}}
```
## Example
1. Open **Integrations** and connect Linear if you have not already done that.
2. Add a **Linear** step to your workflow.
3. Select a connected account in **Authentication**.
4. Choose **Create Issue** in **Action**.
5. In the **Arguments** form, use the **Team** dropdown (auto-populated from your Linear account) to select a team, fill in **Title** and optionally **Description**. Use **Insert Variable** next to any field label to reference an earlier step's output — for example, `{{step_1.output}}` as the issue title.
6. Click **Run** in the step header to test the action, then review the returned payload in **Output**.
## Notes
* This step depends on a connected Linear integration in your workspace.
* The **Raw JSON** tab in Arguments is always available if you prefer to write JSON directly.
* The **Team**, **Project**, and **Issue** fields show dropdowns populated from your connected Linear workspace. If no options load, check that the integration is active in **Integrations**.
* The **Update Issue** action provides an **Issue** dropdown so you can select an existing issue by title rather than entering an ID manually.
## Using Linear as an Agent Tool
You can also add Linear as a tool in the **Agent Editor**. Open the agent, click **Add tool**, and select **Linear**. In the tool settings panel, choose the connected Linear account the agent should use. The agent will create, search, and update issues automatically during conversations when relevant.
See also: [Integrations](../../../workspace/integrations), [Creating and Editing](../../creating-and-editing), and [Testing and Iteration](../../testing-and-iteration)
# Notion
Source: https://docs.fetchhive.com/workflows/steps/integrations/notion
Configure a workflow step that creates a Notion page from workflow content using a connected Notion account
Use **Notion** when you want a workflow step to create a new Notion page from workflow output.
## Configuration
| Option | Required | Description |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Integration Authorization | Yes | The connected Notion account selected in **Authentication**. |
| Parent Page | No | Optional parent page selected in **Parent Page**. |
| Title | Yes | Title entered in **Title**. |
| Icon | No | Emoji selected in **Icon**. |
| Content | Yes | Page body entered in **Content**. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
| Before you configure this step, connect Notion in **Integrations** for your workspace. If no active Notion connection is available, the step shows a warning with a link to **Integrations**. | | |
After you choose an account in **Authentication**, Fetch Hive shows **Parent Page** and lets you pick a destination page or leave it as **No parent page**. Use **Refresh pages** if you want to reload the page list for the selected authorization.
Use the **Insert Variable** button next to **Title** and **Content** if those values should come from start inputs or earlier steps.
The **Content** field supports markdown formatting.
## Output
This step stores the returned Notion page object as the step output.
Use the full output reference in later steps:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
If you want to reference a specific field from the returned Notion payload, insert it from the variable picker after a test run:
```text theme={null}
{{step_2.output.id}}
{{step_2.output.url}}
```
The exact keys depend on the response returned by Notion for the created page.
## Example
Open **Integrations** and connect Notion if needed.
Add **Notion** to your workflow and select the account in **Authentication**.
If you want the page created under an existing page, choose it in **Parent Page**. If the list looks outdated, click **Refresh pages**.
Set **Title**, pick an emoji in **Icon**, and write the page body in **Content**. You can insert values such as `{{step_1.output}}` into the title or body.
Click **Run** to test the step, then inspect **Output** if you want to reuse fields from the returned Notion page object.
## Notes
* **Parent Page** only appears after you select a Notion authorization.
* The **Content** field supports markdown, which Fetch Hive converts into Notion blocks.
* If you leave **Parent Page** unset, the step creates the page without choosing a parent in the step form.
See also: [Integrations](../../../workspace/integrations), [Creating and Editing](../../creating-and-editing), and [Testing and Iteration](../../testing-and-iteration)
# Slack
Source: https://docs.fetchhive.com/workflows/steps/integrations/slack
Configure a workflow step that sends, reads, searches, and manages Slack messages and channels using a connected account
Use **Slack** when you want a workflow step to send messages, read channel history, list channels, search messages, or manage related Slack activity from a connected account.
## Configuration
| Option | Required | Description |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Authentication | Yes | The connected Slack account to use for this step. |
| Action | Yes | The Slack action to perform (for example Send Message, Fetch Conversation History, List All Channels). |
| Arguments | Yes | Per-action form fields generated from the action's schema. Each text field has an **Insert Variable** button for injecting `{{placeholder}}` values. A **Raw JSON** tab is available for advanced usage. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
Before you configure this step, connect Slack in **Integrations** for your workspace using the OAuth flow. If no active connection is available, the step shows a warning with a link to **Integrations** instead of the account selector.
## Arguments form
When you select an action, the **Arguments** section automatically renders a form driven by the action's input schema. Each field includes:
* A label and description from the action's schema.
* An **Insert Variable** button next to eligible fields that injects references like `{{step_1.output.id}}` at the cursor position.
* Validation feedback inline if a required field is left empty.
Switch to the **Raw JSON** tab for power users or when you prefer to write the full arguments object by hand. Changes in either tab stay in sync.
Channel fields often support a picker populated from your connected workspace. Prefer channel IDs when the action requires them.
## Common actions
| Action | Description |
| -------------------------- | ---------------------------------------------------- |
| Send Message | Post a message to a channel, DM, or private group. |
| Schedule Message | Schedule a message for later delivery. |
| Update Message | Edit an existing Slack message. |
| Fetch Conversation History | Read recent messages from a channel or conversation. |
| Fetch Message Thread | Retrieve replies in a message thread. |
| Search Messages | Search messages across the workspace. |
| List All Channels | List channels available to the connected account. |
| Find Channels | Search for channels by name or related criteria. |
| Find Users | Look up users in the workspace. |
| Join Conversation | Join an existing public conversation. |
| Open DM | Open a direct message conversation. |
| Create Reminder | Create a Slack reminder. |
| Upload File | Upload or create a file in Slack. |
| Add Reaction | Add an emoji reaction to a message. |
| Test Auth | Confirm the connected account is valid. |
Destructive actions such as deleting messages, deleting channels, or removing users are not exposed in the workflow action picker.
## Output
This step stores the Slack API response as the step output. The shape of the response depends on the action.
Use the full output reference in later steps:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
For example, after a **Send Message** step you might reference fields from the returned payload:
```text theme={null}
{{step_2.output.ts}}
```
## Example
1. Open **Integrations** and connect Slack if you have not already done that.
2. Add a **Slack** step to your workflow.
3. Select a connected account in **Authentication**.
4. Choose **Fetch Conversation History** in **Action** to collect channel messages, or **Send Message** to post.
5. In the **Arguments** form, fill in the channel and any message text. Use **Insert Variable** to reference an earlier step's output for any field value.
6. Click **Run** in the step header to test the action, then review the returned payload in **Output**.
## Notes
* This step depends on a connected Slack integration in your workspace.
* The workflow action picker shows a curated subset of Slack actions. Agents with the Slack tool can access additional safe actions.
* OAuth may show third-party authorization branding during the connect flow.
* If you previously connected Slack before the multi-action update, reconnect Slack in **Integrations** so the account can use the expanded action set.
## Using Slack as an Agent Tool
You can also add Slack as a tool in the **Agent Editor**. Open the agent, click **Add tool**, and select **Slack**. In the tool settings panel, choose the connected account the agent should use. The agent will call Slack actions automatically during conversations when relevant.
See also: [Integrations](../../../workspace/integrations), [Creating and Editing](../../creating-and-editing), and [Testing and Iteration](../../testing-and-iteration)
# Telegram
Source: https://docs.fetchhive.com/workflows/steps/integrations/telegram
Send a plain text Telegram message from a workflow
Use **Telegram** when you want a workflow to send a plain text message to your private Telegram chat.
Telegram steps send messages from the Fetch Hive Bot. You do not need to create a Telegram bot or add a bot token.
## Setup
### 1. Connect Telegram
Open the workspace **Integrations** page and click **Connect** on Telegram.
You can also connect from a Telegram workflow step by clicking **Connect Telegram** in the **Destination** field.
### 2. Start the Fetch Hive Bot
Telegram opens the Fetch Hive Bot.
Press **Start** in Telegram. If Telegram shows a message box instead, send the prefilled `/start` message.
If the **Start** button on the Telegram web page does nothing, your browser probably cannot open Telegram on that device. Open the same link on a phone or computer where you are logged in to Telegram, or open Telegram yourself, search for `@FetchHiveBot`, and send the `/start` message shown in the link.
The `/start` link expires after a short time. If it does not work, return to Fetch Hive and click **Connect Telegram** again to get a fresh link.
### 3. Return to Fetch Hive
Return to Fetch Hive after pressing **Start**.
The connected Telegram destination appears in the Telegram step **Destination** picker. If it does not appear immediately, click **Refresh**.
### 4. Add the Telegram step
Add **Telegram** to your workflow.
Keep **Action** set to **Send Message**.
Choose your connected Telegram destination.
If a workflow assistant adds the Telegram step for you, open the step settings and choose the destination before testing, running, versioning, or deploying the workflow.
Write the message body in **Message**. Use **Insert Variable** when the message should include a start input or an earlier workflow step output.
## Configuration
| Option | Required | Description |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Action | Yes | The Telegram action. The current editor shows **Send Message**. |
| Destination | Yes | Your connected private Telegram chat. |
| Message | Yes | Plain text message body. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if Telegram delivery fails. |
## Example
A common scheduled workflow is:
```text theme={null}
RSS or search step -> prompt summary step -> Telegram step
```
In the Telegram message, reference the prior summary:
```text theme={null}
{{summary_step.output}}
```
Scheduled workflows work normally once Telegram is connected and selected, which makes this useful for daily news summaries, alerts, and recurring reports.
## Output
This step stores the Telegram response as the step output.
Use the full output reference in later steps:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
If you need a specific field from the returned Telegram payload, insert it from the variable picker after a test run:
```text theme={null}
{{step_2.output.result.message_id}}
```
Telegram limits each bot text message to 4096 characters. If the resolved message is longer, Fetch Hive sends it as multiple Telegram messages. In that case the output includes `message_count`, and `result` is a list of Telegram message payloads.
## Notes
* Telegram must be connected by the same user who selects the destination.
* This setup supports private Telegram chats.
* The step sends plain text only.
* Group and channel destinations are not part of the normal Telegram step setup yet.
See also: [Scheduled Deployments](../../scheduled-deployments), [Testing and Iteration](../../testing-and-iteration), and [Integrations](../../../workspace/integrations)
# Search Knowledge Base
Source: https://docs.fetchhive.com/workflows/steps/knowledge-base/search-knowledge-base
Configure a workflow step that runs a semantic, keyword, or hybrid search against an existing knowledge base and stores the results
Use **Search Knowledge Base** when you want a workflow step to query one of your knowledge bases and pass the matching chunks to later steps — for example, feeding retrieved context into an AI Prompt step.
## Configuration
| Option | Required | Description |
| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Knowledge Base | Yes | The knowledge base to search, selected in **Knowledge Base**. |
| Search Query | Yes | The query string. This field supports workflow variables through **Insert Variable**. |
| Search Type | No | One of **Hybrid**, **Semantic**, or **Keyword**. Defaults to **Hybrid**. |
| Result Limit | No | Maximum number of matching chunks to return (1–20, default 5). |
| Score Threshold | No | Minimum relevance score required to include a result (0.0–1.0, default 0.0). A value of 0.0 returns all results up to the limit regardless of score. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
### Search Type
* **Hybrid** — Combines vector similarity and keyword matching. Recommended for most queries.
* **Semantic** — Pure vector similarity search. Best for conceptual or natural-language queries.
* **Keyword** — Full-text keyword search. Best for exact-match or structured queries.
### Result Limit
Controls how many chunks are returned. Higher limits increase context available to downstream steps but may also increase noise. The slider accepts values from 1 to 20.
### Score Threshold
Filters out low-relevance results. Raise this value (toward 1.0) to return only highly confident matches. Leave it at 0.0 to return all results up to the limit.
## Output
This step returns the matching chunks from the knowledge base:
```json theme={null}
[
{
"content": "...",
"score": 0.87,
"metadata": { ... }
},
...
]
```
Reference the full result set in a later step:
```text theme={null}
{{step_2.output}}
```
A common pattern is to pass the output directly into an AI Prompt step as context:
```text theme={null}
Answer the following question using only the context below.
Context:
{{step_2.output}}
Question: {{start.query}}
```
## Cost
Each run of this step costs **1 task**.
## Example
Add **Search Knowledge Base** from the **Knowledge Base** group in **Search steps...**.
Set **Knowledge Base** to the knowledge base you want to query.
Enter the user's question in **Search Query**, or insert a variable from a start input: `{{start.question}}`.
Leave **Search Type** as **Hybrid** unless you have a specific reason to prefer pure semantic or keyword search.
Adjust **Result Limit** to control how many chunks are returned. Start with 5 and increase if answers seem incomplete.
Set **Score Threshold** to 0.5 or higher if you want to exclude low-confidence matches.
Click **Run** in the step header to test the search. Review the returned chunks in **Output**, then connect the output to an AI Prompt step to generate an answer.
## Notes
* The effective search type falls back to the knowledge base's own default if the step setting is left at its default value.
* Score values are normalised to the 0–1 range. The exact meaning depends on the underlying embedding model and search backend.
* Search queries and results are logged as knowledge base search audit records for monitoring.
See also: [Write to Knowledge Base](./write-knowledge-base), [AI Prompt](../ai/ai-prompt), [Creating and Editing](../../creating-and-editing), [Testing and Iteration](../../testing-and-iteration), and [Error Handling](../../error-handling)
# Search Pinecone
Source: https://docs.fetchhive.com/workflows/steps/knowledge-base/search-pinecone
Search a selected Pinecone namespace in a workflow
Add **Search Pinecone** from the **Knowledge Base** group. Select a ready dense index with integrated embedding, choose an existing namespace, enter a query (workflow variables are supported), and set a result limit from 1 to 20. New namespaces can only be created with **Write to Pinecone**.
The result contains the query, saved index and namespace, and normalized matches with `id`, `score`, `text`, and `metadata`. The step does not create Fetch Hive Knowledge Base records.
# Write to Knowledge Base
Source: https://docs.fetchhive.com/workflows/steps/knowledge-base/write-knowledge-base
Configure a workflow step that writes content to an existing knowledge base — from custom text, a document, or a scraped website
Use **Write to Knowledge Base** when you want a workflow step to add new content to one of your knowledge bases. Each run creates a new knowledge base item so that the full history of writes is preserved.
## Configuration
| Option | Required | Description |
| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Knowledge Base | Yes | The target knowledge base selected in **Knowledge Base**. |
| Write Mode | Yes | One of **Text**, **Document**, or **Scrape**. |
| Content | Yes (Text mode) | The text to embed. This field supports workflow variables through **Insert Variable**. |
| Document URL | Yes (Document mode) | The URL of the document to extract and embed. Supports workflow variables through **Insert Variable**. |
| Website URL | Yes (Scrape mode) | The URL to scrape. |
| Chunking Strategy | No | **Default** uses deterministic paragraph- and sentence-aware chunking. **Advanced** uses the same chunker and lets you set **Max Chunk Length** and **Chunk Overlap** manually. |
| Remove Email Addresses | No | When enabled, strips email addresses from the content before embedding. |
| Remove Phone Numbers | No | When enabled, strips phone numbers from the content before embedding. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
### Write Mode
**Text** — Enter raw text directly in **Content** or pipe in a prior step's output using `{{step_n.output}}`.
**Document** — Enter a document URL in **Document URL**, or use **Insert Variable** to pass a URL from a prior step (for example, a media library asset URL). The content is extracted automatically and embedded into the knowledge base.
**Scrape** — Enter a URL in **Website URL**. Fetch Hive scrapes the page and embeds the extracted text.
### Chunking Strategy
Leave **Chunking Strategy** set to **Default** for most use cases. Fetch Hive preserves paragraph and sentence boundaries where possible, and only falls back to hard splitting when a single unit is too large. Switch to **Advanced** to control exactly how the content is split:
* **Max Chunk Length** — Maximum number of characters per chunk (default 500).
* **Chunk Overlap** — Number of characters shared between adjacent chunks (default 50). Overlap helps preserve context at chunk boundaries.
### PII Removal
Enable **Remove Email Addresses** and/or **Remove Phone Numbers** to redact those values from the content before it is embedded and stored.
## Output
This step returns a summary of the write operation:
```json theme={null}
{
"knowledge_base_item_id": "...",
"knowledge_base_id": "...",
"chunk_count": 12,
"status": "completed",
"write_mode": "custom_text"
}
```
Reference the output in a later step:
```text theme={null}
{{step_2.output}}
{{step_2.output.chunk_count}}
```
## Cost
Each run of this step costs **1 task**.
## Example
Add **Write to Knowledge Base** from the **Knowledge Base** group in **Search steps...**.
Set **Knowledge Base** to the target knowledge base.
Choose **Write Mode**. For a pipeline that summarises web articles, select **Scrape** and set **Website URL** to `{{step_1.output.url}}`.
Leave **Chunking Strategy** as **Default** unless you need precise control over chunk size.
Enable **Remove Email Addresses** if the scraped content may contain personal data.
Click **Run** in the step header to test the write, then check **Output** to confirm the chunk count and item ID.
## Notes
* Each run creates a **new** knowledge base item. Prior items written by earlier runs are not overwritten, so the full write history is preserved in the knowledge base.
* The step validates that a knowledge base is selected and that the required input for the chosen mode is present before running.
* Chunking and PII removal are applied before the content is embedded.
See also: [Search Knowledge Base](./search-knowledge-base), [Creating and Editing](../../creating-and-editing), [Testing and Iteration](../../testing-and-iteration), and [Error Handling](../../error-handling)
# Write to Pinecone
Source: https://docs.fetchhive.com/workflows/steps/knowledge-base/write-pinecone
Write one text record to a selected Pinecone namespace
Add **Write to Pinecone** from the **Knowledge Base** group. Select a compatible index and namespace, then enter the text to write. Workflow variables are supported.
Record ID is optional; leaving it blank generates a UUID. Supplying an existing ID replaces the complete record. Optional metadata must be a flat JSON object containing strings, finite numbers, booleans, or arrays of strings.
Each run writes exactly one record. New namespaces appear after the first write. Pinecone is eventually consistent, so the receipt is returned without polling for search visibility.
# Overview
Source: https://docs.fetchhive.com/workflows/steps/overview
Browse workflow step categories and configuration pages
Workflow steps are the building blocks of a workflow. Each step performs one action — fetching data, transforming it, calling an API, writing to a knowledge base, and so on — and passes its output to the next step via workflow variables.
## Step groups
### AI
Generate text, structured data, or images using large language models.
* [AI Prompt](ai/ai-prompt)
* [Agent](ai/agent)
* [Image Generation](ai/image-generation)
* [Google AI Overview](ai/google-ai-overview)
* [Google AI Mode](ai/google-ai-mode)
### Web Research
Search the web and scrape pages.
* [Google Search](web-research/google-search)
* [Google News](web-research/google-news)
* [Bing Search](web-research/bing-search)
* [Exa Search](web-research/exa-search)
* [Perplexity Search](web-research/perplexity-search)
* [Exa Similar](web-research/exa-similar)
* [Copilot Search](web-research/copilot-search)
* [Website Scrape](web-research/website-scrape)
* [RSS Feed](web-research/rss-feed)
### Knowledge Base
Write content to and retrieve content from your knowledge bases.
* [Write to Knowledge Base](knowledge-base/write-knowledge-base)
* [Search Knowledge Base](knowledge-base/search-knowledge-base)
### Utility
Transform data and generate files.
* [Human in the Loop](utility/human-in-the-loop)
* [Condition](utility/condition)
* [JSON Schema](utility/json-schema)
* [Data Transform](utility/data-transform)
* [Custom API](utility/custom-api)
* [Extract from File](utility/extract-from-file)
* [Generate File](utility/generate-file)
### Integrations
Send data to connected third-party services.
* [Slack](integrations/slack)
* [ElevenLabs](integrations/elevenlabs)
* [Telegram](integrations/telegram)
* [Notion](integrations/notion)
* [Google Docs](integrations/google-docs)
* [Google Sheets](integrations/google-sheets)
### Advanced
Compose and orchestrate complex workflows.
* [Sub-workflow](advanced/sub-workflow)
# Condition
Source: https://docs.fetchhive.com/workflows/steps/utility/condition
Configure a workflow step that branches execution into a TRUE or FALSE path based on a boolean expression over workflow variables
Use **Condition** when you want a workflow to take a different path depending on the value of an earlier step's output or a start input. The Condition step evaluates a boolean expression and routes execution down a **TRUE** or **FALSE** branch. Both branches must eventually rejoin at a single merge step before the workflow can continue.
Reach for this step when you need if/else logic, gated steps (for example, only send an email when a score is above a threshold), or lightweight A/B splits inside a workflow.
## Configuration
| Option | Required | Description |
| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Condition | Yes | The boolean expression that decides which branch runs. Built in the **Condition builder** as one or more rows, optionally nested in `AND` / `OR` / `NOT` groups. |
| Branches rejoin at | — | Read-only. Shown once both branches converge on a merge step. |
Add this step from the **Utilities** group in **Search steps...**. In the step picker, the label is **Condition**.
When you insert a Condition, Fetch Hive automatically creates an empty **TRUE** branch and an empty **FALSE** branch that both initially point at whatever step used to follow the insertion point. Use the `+` handles on each branch to add steps into that side of the branch from the canvas.
### Adding steps with Workflow Copilot
Workflow Copilot distinguishes three placements around a Condition:
* **TRUE branch of *Condition name*** — the step runs only when the expression evaluates to true.
* **FALSE branch of *Condition name*** — the step runs only when the expression evaluates to false.
* **After branches rejoin for *Condition name*** — the step runs after either result, once the two paths converge.
The proposed action card shows this placement separately from its description. Check that line before clicking **Apply**. If your request only says "under" or "after" a Condition, Copilot should ask which of these three locations you mean instead of choosing a branch.
### Operators
The **Condition builder** supports these operators:
* Group operators: `AND`, `OR`, `NOT` — combine multiple rows or negate a sub-expression.
* Leaf operators:
* `equals`, `does not equal`
* `>`, `>=`, `<`, `<=`
* `contains`, `starts with`, `ends with`
* `is one of`
* `exists`, `is empty` — take only a left-hand operand
### Operands
Each clause compares a **left** operand against a **right** operand (except `exists` and `is empty`, which only take a left operand).
Operands are either:
* A **workflow variable** — click **Insert Variable** to reference a start input (`{{variable_name}}`) or a previous step's output (`{{step_2.output.score}}`).
* A **literal value** — type a string, number, boolean, or array directly into the right-hand field.
## Output
Click **Run** in the step header to test the Condition. Fetch Hive shows the evaluated boolean result and a trace of the resolved left/right operands in **Output** after the run completes.
During a real workflow run, only one branch executes — the one matching the boolean result. The step's base reference is:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
Which resolves to `true` or `false` for later steps that want to reference the branch decision itself.
## Example
Add **Condition** from the **Utilities** group in **Search steps...**.
Set **Name** to something like `Score above threshold`.
In the **Condition builder**:
1. On the left operand, click **Insert Variable** and pick `{{step_2.output.score}}`.
2. Choose the `>` operator.
3. On the right operand, pick **Literal** and type `70`.
Click **Run** to confirm the expression evaluates the way you expect against the last test output. Then add the "send email" step into the **TRUE** branch on the canvas so it only runs when the score is above 70. The **FALSE** branch can stay empty (it rejoins the merge step directly) or you can add an alternative path.
## Notes
* The expression must be complete before saving. Every row needs both a left and right operand (except `exists` / `is empty`, which only take a left operand).
* The evaluator is lenient with numeric-looking strings — comparing `"70"` to `70` works as you would expect.
* Removing a Condition also removes every step inside its TRUE and FALSE branches. Move or recreate any branch steps you want to keep before removing the Condition.
* Both branches must converge at a single merge step for the workflow to be valid. Fetch Hive surfaces a warning if the branches don't rejoin.
* A Condition can be nested inside another Condition branch. Each Condition still needs its own TRUE and FALSE paths to converge on a valid merge point.
See also: [Creating and Editing](../../creating-and-editing), [Testing and Iteration](../../testing-and-iteration), and [Error Handling](../../error-handling)
# Custom API
Source: https://docs.fetchhive.com/workflows/steps/utility/custom-api
Configure a workflow step that makes an HTTP request and stores the response for later steps
Use **Custom API** when you want a workflow step to call an external HTTP endpoint from Fetch Hive and pass the response to later steps.
## Configuration
| Option | Required | Description |
| -------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| API Method | Yes | HTTP method in **API Method**. Available values are `get` and `post`. |
| API URL | Yes | URL in **API URL**. This field supports workflow variables through **Insert Variable**. |
| Headers | No | JSON string entered in **Headers**. |
| Body | No | JSON string entered in **Body**. This field is only shown when **API Method** is `POST`. |
| Retry Count | No | Number of retries in **Retry Count**. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
| Add this step from the **Utilities** group in **Search steps...**. In the step picker, the label is **Call an API**. | | |
The settings sheet has separate fields for **API URL**, **Headers**, and **Body**. Each field can include values from **Inputs** or previous **Workflow Steps** with **Insert Variable**.
## Output
Click **Run** in the step header to test the request. Fetch Hive shows the response in **Output** after the run completes.
Use the variable picker in a later step to insert the exact response path available for that run. The base reference is:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
If you only need the full response payload, reference the base output directly:
```text theme={null}
{{step_2.output}}
```
If the response is a structured object, the variable picker shows the nested fields you can insert into later steps.
## Example
Add **Call an API** from the **Utilities** group in **Search steps...**.
Set **Name** to something like `Fetch customer profile`.
Choose **GET** or **POST** in **API Method**.
Enter the endpoint in **API URL**. If the endpoint needs data from earlier steps, click **Insert Variable** and add values such as `{{step_1.output.customer_id}}`.
If the request needs authentication or content headers, add them in **Headers** as JSON. If you use **POST**, add the request payload in **Body**.
Adjust **Retry Count** and choose what should happen in **When the step fails**.
Click **Run** and review the API response in **Output** before you wire that output into later steps.
## Notes
* The step picker label is **Call an API**, even though this page and file use **Custom API**.
* The deployment read-only view shows the URL, method, retry count, and failure behavior. It does not show the full headers or request body summary there.
* Use valid JSON in **Headers** and **Body** if your downstream API expects JSON payloads.
See also: [Creating and Editing](../../creating-and-editing), [Testing and Iteration](../../testing-and-iteration), and [Error Handling](../../error-handling)
# Data Transform
Source: https://docs.fetchhive.com/workflows/steps/utility/data-transform
Reshape workflow data by building rows, concatenating arrays, or flattening an array without calling an external service
Use **Data Transform** when you need to reshape existing workflow output before another step reads it.
Data Transform does not call an external service. It is useful after **Extract from File**, before **Google Sheets**, **Airtable**, **Custom API**, and follow-up **Iteration** steps.
## Configuration
| Option | Required | Description |
| --------------- | ------------------ | ------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Mode | Yes | The transform to run. Choose **Build Rows**, **Concat Arrays**, or **Flatten Array**. |
| Fields | Build Rows only | Output object keys and their source values. |
| Sources | Concat Arrays only | Array values to append into one array. |
| Source Value | Flatten Array only | One array value to flatten by one level. |
| Mismatch Policy | Build Rows only | How to handle arrays with different lengths. |
Add this step from the **Utilities** group in **Search steps...**.
## Modes
### Build Rows
Use **Build Rows** to zip arrays by index into an array of objects.
Each field has a **Key** and **Source Value**. The key becomes an object property. The source can be a whole variable reference such as `{{tool_names}}` or `{{step_3.output}}`, or a static value.
Array source values are read by index. Static scalar values repeat for every row.
Example:
```json theme={null}
{
"tool_names": ["Exa", "Airtable"],
"search_contexts": ["Search context for Exa", "Search context for Airtable"]
}
```
Build Rows fields:
```json theme={null}
[
{ "key": "tool_name", "value": "{{tool_names}}" },
{ "key": "search_context", "value": "{{search_contexts}}" },
{ "key": "workspace", "value": "Fetch Hive" }
]
```
Output:
```json theme={null}
[
{
"tool_name": "Exa",
"search_context": "Search context for Exa",
"workspace": "Fetch Hive"
},
{
"tool_name": "Airtable",
"search_context": "Search context for Airtable",
"workspace": "Fetch Hive"
}
]
```
Use **Mismatch Policy** when array lengths differ:
| Policy | Behavior |
| ----------- | --------------------------------------------------------------------------------- |
| Pad null | Uses the longest array and fills missing values with `null`. This is the default. |
| Strict fail | Fails the step if array lengths do not match. |
| Truncate | Uses the shortest array length. |
### Concat Arrays
Use **Concat Arrays** to append multiple arrays into one longer array.
Each source must resolve to an array. If a source resolves to a string, object, number, or boolean, the step fails.
Example sources:
```json theme={null}
[
{ "value": "{{step_2.output}}" },
{ "value": "{{step_3.output}}" }
]
```
If those values are `["a", "b"]` and `["c"]`, the output is:
```json theme={null}
["a", "b", "c"]
```
### Flatten Array
Use **Flatten Array** to flatten one array by one level.
Nested array elements expand. Non-array elements stay in place.
Example source:
```json theme={null}
[[1, 2], 3, [4]]
```
Output:
```json theme={null}
[1, 2, 3, 4]
```
## Output
Data Transform stores its result at:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
For **Build Rows**, the output is an array of objects. This shape works well with integration steps that expect records or rows.
For **Concat Arrays** and **Flatten Array**, the output is an array that later steps can iterate over.
## Notes
* Source values should be whole placeholders such as `{{step_2.output}}`, or static scalar values.
* Mixed template strings such as `Research for {{tool_names}}` are not supported in Data Transform V1.
* Data Transform preserves arrays and objects as structured JSON for downstream steps.
* Data Transform is a free utility step.
See also: [Google Sheets](../integrations/google-sheets), [Airtable](../integrations/airtable), [Custom API](custom-api), and [Testing and Iteration](../../testing-and-iteration)
# Extract from File
Source: https://docs.fetchhive.com/workflows/steps/utility/extract-from-file
Configure a workflow step that fetches a file from a URL and extracts rows or text for later steps
Use **Extract from File** when you want a workflow step to read structured or text data from a public file URL inside Fetch Hive.
## Configuration
| Option | Required | Description |
| ------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| File URL | Yes | URL in **File URL**. This field supports workflow variables through **Insert Variable**. |
| File format | No | Auto-detect from the URL extension, or choose JSON, CSV, XLSX, XLS, HTML, DOCX, PDF, or XML manually. |
| Sheet index | Tabular only | Zero-based sheet index for XLS and XLSX files. Defaults to `0`. |
| First row is header | Tabular only | When enabled, CSV and spreadsheet files use the first row as column names. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
Add this step from the **Utilities** group in **Search steps...**.
Supported formats:
| Format | Output shape |
| --------------- | ---------------------- |
| CSV, XLSX, XLS | Array of row objects |
| JSON, XML | Parsed object or array |
| HTML, DOCX, PDF | Plain text string |
Tabular outputs are clamped to your plan iteration limit and a platform safety cap of 1,000 rows.
## Output
Click **Run** in the step header to test the step. Fetch Hive shows the extracted result in **Output** after the run completes.
Use the variable picker in a later step to insert the exact output path for your run. The base reference is:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
For CSV or spreadsheet files, `{{STEP_IDENTIFIER.output}}` **is** the array of row objects (there is no `.rows` or `.items` wrapper). Pass it directly into an **Iteration** step:
```text theme={null}
{{extract_contacts.output}}
```
Do **not** use `{{extract_contacts.output.rows}}` or `{{extract_contacts.output.items}}` — those paths resolve to null.
### Field names
When **First row is header** is enabled, column headers are converted to
variable-safe snake\_case keys before they become row object properties:
| Header in file | Row key |
| ---------------------- | ------------------------- |
| `Company name` | `company_name` |
| `Company's country` | `companys_country` |
| `Add date` | `add_date` |
| (blank / symbols only) | `column_1`, `column_2`, … |
Duplicate sanitized keys get numeric suffixes (`company_name`, `company_name_2`).
Inside the iteration body, reference fields from each row:
```text theme={null}
{{contacts_loop.item.company_name}}
{{contacts_loop.item.website}}
```
## Example
Add **Extract from File** from the **Utilities** group.
Set **File URL** to a public CSV such as `https://example.com/contacts.csv`.
Keep **File format** on **Auto-detect** and leave **First row is header** enabled.
Add an **Iteration** step with source `{{extract_contacts.output}}`.
Inside the loop:
1. **Website Scrape** on `{{contacts_loop.item.website}}`
2. **AI Prompt** to write a unique outreach fact from the scrape result
After the loop, use **Data Transform** or **Google Sheets** to collect enriched rows.
## Notes
* Use a directly reachable file URL. This step fetches the file over HTTP; it does not upload files from your computer.
* HTML extraction returns full-page text, not table rows.
* PDF and DOCX extraction returns text suitable for downstream **AI Prompt** steps.
* **Breaking change:** older workflows that referenced raw header strings with spaces (e.g. `{{contacts_loop.item.Company name}}`) must be updated to the snake\_case keys after re-running the extract step.
See also: [Data Transform](./data-transform), [Creating and Editing](../../creating-and-editing), [Testing and Iteration](../../testing-and-iteration), and [Error Handling](../../error-handling)
# Generate File
Source: https://docs.fetchhive.com/workflows/steps/utility/generate-file
Configure a workflow step that generates a PDF, Word, Excel, or CSV file and stores it in your media library
Use **Generate File** when you want a workflow step to create a downloadable file that later steps or runs can reference. The generated file is stored in the workspace media library.
## Configuration
| Option | Required | Description |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------ |
| Name | No | Label for the step in the workflow canvas. |
| File format | Yes | Output format: **PDF**, **Word (DOCX)**, **Excel (XLSX)**, or **CSV**. |
| Filename | No | Optional name for the generated file. Leave blank to use the step identifier. |
| Content | Yes | Source content for the file. This field supports workflow variables through **Insert Variable**. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
Add this step from the **Generation** group in **Search steps...**.
### Content by format
* **PDF** and **Word (DOCX)** use markdown. Headings, lists, tables, and emphasis are converted into the generated document.
* **Excel (XLSX)** and **CSV** accept CSV text or a JSON array of objects. Put CSV headers in the first row, or insert a variable that resolves to an array of objects — object keys become column headers.
Use **Insert Variable** to combine text from **Inputs** or earlier **Workflow Steps** before you generate the file.
## Output
Click **Run** in the step header to test the step. Fetch Hive shows the generated file in **Output** after the run completes. The file is also saved to the workspace media library.
Use the variable picker in a later step to insert the exact output path available for that run. The base reference is:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
Use the variable picker if you need a deeper field or file reference from the generated result.
## Cost
Each run of this step costs **1 task**, for every output format.
## Example
Add **Generate File** from the **Generation** group in **Search steps...**.
Set **Name** to something like `Create weekly report`.
Choose **PDF** as the file format.
Write the document in **Content** with markdown headings, lists, and inserted workflow values such as `{{step_2.output.summary}}`.
Choose what should happen in **When the step fails**.
Click **Run** and check **Output** to confirm the generated result before using it elsewhere in the workflow.
## Notes
* This page lives under `utility` in the docs tree, but the actual step appears under **Generation** in the Fetch Hive step picker.
* Existing **PDF Generation** steps are now **Generate File** steps with the PDF format selected.
* Google Docs and Google Sheets remain separate integration steps when you want to create a document in a connected Google account instead of storing a file in the media library.
See also: [Creating and Editing](../../creating-and-editing), [Testing and Iteration](../../testing-and-iteration), and [Error Handling](../../error-handling)
# Human in the Loop
Source: https://docs.fetchhive.com/workflows/steps/utility/human-in-the-loop
Pause a workflow for a person to choose, respond, approve, or reject
Pause a workflow and ask one workspace member to choose from a list of options, provide a text response, or approve/reject a gate before the workflow continues.
Use this when a workflow can gather or prepare candidate options automatically, but a person needs to make the final selection. For example, an RSS step can fetch new articles, then a Human in the Loop step can ask a teammate which article should be researched next.
## Configuration
| Field | Description |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Question / approval title | The main question or title shown to the recipient on the approval page and in the notification. In Approval mode, this is the approval title. |
| Response mode | Choose **Choices** for a selectable list, **Text area** for a required typed answer, or **Approval** for fixed Approve/Reject actions. |
| Options source | A variable expression that resolves to a flat array, such as `{{rss_step.output.items}}` for a single-run RSS feed. Only used in Choices mode. When the upstream step is parallelized, its output is an array — a bare field like `{{rss_step.output.items}}` resolves to null. Pluck with `{{rss_step.output.*.items}}` (array of arrays) and flatten via a **Data Transform** step before using it here. |
| Label path | Optional relative path used as each option's visible label, such as `title` or `source.title`. |
| Value path | Optional relative path used as the selected value, such as `url` or `metadata.slug`. |
| Description path | Optional relative path used as supporting text for each option, such as `summary` or `content.excerpt`. |
| Recipient | The workspace member allowed to make the choice when the notification channel is Email. |
| Notification channel | Email or Telegram. |
| Telegram destination | The connected Fetch Hive bot destination used when the notification channel is Telegram. |
| Link TTL | How long the approval link token remains valid before the recipient must request a fresh link. |
| Wait timeout | How long the workflow waits before the step fails or continues according to the failure behavior. |
The label, value, and description fields are paths relative to each item in the options array. They only apply in Choices mode. The editor can suggest paths from the first sample item when the options source resolves from existing step output or start-input examples. Nested same-name fields can be disambiguated with full paths, such as `source.title` and `author.title`. Duplicate keys in the same JSON object cannot be distinguished after JSON parsing.
## Output
The step always returns the same top-level object so later steps can be wired before the workflow runs.
Choices mode returns the selected option:
```json theme={null}
{
"response_type": "choice",
"choice": {
"id": "option_1",
"label": "Example article",
"value": "https://example.com/article",
"description": "Short summary",
"raw": {}
},
"text": "",
"files": [],
"metadata": {}
}
```
Before a run completes, downstream steps can still be wired against the same empty shape:
```json theme={null}
{
"text": "",
"files": [],
"choice": {
"id": "",
"label": "",
"value": "",
"description": "",
"raw": {}
},
"metadata": {},
"response_type": "choice"
}
```
Text mode returns the typed answer:
```json theme={null}
{
"text": "Submitted answer",
"files": [],
"choice": {
"id": "",
"label": "",
"value": "",
"description": "",
"raw": {}
},
"metadata": {},
"response_type": "text"
}
```
Approval mode returns the selected decision. Approve lets the workflow continue:
```json theme={null}
{
"text": "",
"files": [],
"choice": {
"id": "approved",
"label": "Approved",
"value": "approved",
"description": "",
"raw": { "approved": true }
},
"metadata": {
"approved": true,
"rejected": false
},
"response_type": "approval"
}
```
Reject intentionally stops the workflow and marks the run as completed:
```json theme={null}
{
"text": "",
"files": [],
"choice": {
"id": "rejected",
"label": "Rejected",
"value": "rejected",
"description": "",
"raw": { "approved": false }
},
"metadata": {
"approved": false,
"rejected": true
},
"response_type": "approval"
}
```
Downstream steps reference the actual step identifier shown in the workflow builder. For example, if this step is `step_5`, use:
| Variable | Use |
| -------------------------------------- | -------------------------------------------------------------------------- |
| `{{step_5.output.text}}` | The submitted text answer in Text area mode. Empty in Choices mode. |
| `{{step_5.output.choice.value}}` | The selected option value in Choices mode. |
| `{{step_5.output.choice.label}}` | The selected option label in Choices mode. |
| `{{step_5.output.choice.description}}` | The selected option description in Choices mode. |
| `{{step_5.output.choice.raw.url}}` | A field from the original selected option object, when that field exists. |
| `{{step_5.output.metadata.approved}}` | `true` when Approval mode was approved. |
| `{{step_5.output.metadata.rejected}}` | `true` when Approval mode was rejected. |
| `{{step_5.output.response_type}}` | `choice`, `text`, or `approval`, depending on how the recipient responded. |
## Runtime
The workflow is paused while waiting for the recipient. Fetch Hive sends a short-lived approval link by the configured notification channel. Email mode sends to the selected recipient. Telegram mode sends to the selected Telegram destination. If the link expires, the recipient can request a fresh link from the approval page.
Only the configured recipient can view and submit the choice, and they must still belong to the workflow workspace.
In Approval mode, Approve resumes the workflow normally. Reject is treated as an intentional stop: Fetch Hive records the rejected output, skips remaining workflow steps, and marks the workflow run as completed rather than failed.
## API Behavior
Deployed workflows that contain Human in the Loop must run asynchronously with a callback URL. Synchronous API invocation returns a validation error because the workflow cannot finish until the human response is submitted.
## Cost
Human in the Loop uses a fixed workflow-step credit charge and does not call an LLM by itself.
## Notes
* Human in the Loop does not support step-level parallelization.
* Human in the Loop cannot be placed inside an iteration body in the current version.
* If the wait timeout expires, the step follows its configured failure behavior: terminate or continue.
* A timeout is not the same as Reject. Timeouts follow the failure behavior; Reject completes the run intentionally.
# JSON Schema
Source: https://docs.fetchhive.com/workflows/steps/utility/json-schema
Configure a workflow step that defines structured fields and returns JSON-shaped output for later steps
Use **JSON Schema** when you want a workflow step to define a structured output shape that later steps can reference field by field.
## Configuration
| Option | Required | Description |
| ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Schema Items | Yes | Rows in **Schema Items**. Each row has a **Key** and a **Value / Description** field. |
| Add this step from the **Utilities** group in **Search steps...**. | | |
In **Schema Items**, click **Add Item** to add another field. Each row lets you define the output key and describe the value that key should hold. The **Value / Description** field supports **Insert Variable**.
If a value resolves to a JSON array or object, Fetch Hive stores it as structured JSON rather than a string. For example, a value of `{{step_2.output.items}}` can produce an array that an **Iteration** step can use later. You can also build a JSON array literal from multiple array variables, such as `[{{step_2.output.items}},{{step_3.output.items}}]`; this creates an array of arrays, not a flattened concatenation.
## Output
Click **Run** in the step header to test the step. Fetch Hive shows the generated result in **Output** after the run completes.
Use the variable picker in a later step to insert the exact output path for your run. The base reference is:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
If you want the full structured result, reference the base output directly:
```text theme={null}
{{step_2.output}}
```
If your run returns nested keys, the variable picker shows the exact fields you can insert into later steps.
## Example
Add **JSON Schema** from the **Utilities** group in **Search steps...**.
Set **Name** to something like `Article fields`.
In **Schema Items**, add keys such as `title`, `summary`, and `sentiment`.
For each item, describe what the value should contain in **Value / Description**. If a field should depend on earlier workflow data, click **Insert Variable** and add that reference.
Click **Run** and review the structured result in **Output** before using those keys in later steps.
## Notes
* The settings sheet lets you add and remove schema rows with **Add Item** and the delete action on each row.
* This step editor does not show a **When the step fails** control in its settings sheet.
* JSON Schema preserves resolved JSON arrays and objects for downstream steps, including **Iteration**. It does not currently merge two arrays into one flat array automatically.
* Use the variable picker after a test run if you want to confirm the exact keys available to later steps.
See also: [Creating and Editing](../../creating-and-editing), [Testing and Iteration](../../testing-and-iteration), and [AI Prompt](../ai/ai-prompt)
# Bing Search
Source: https://docs.fetchhive.com/workflows/steps/web-research/bing-search
Configure a workflow step that searches Bing and stores the results for later steps
Use **Bing Search** when you want a workflow step to search the web through Bing and pass the results into later workflow steps in Fetch Hive.
## Configuration
| Option | Required | Description |
| ----------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Search Query | Yes | Query in **Search Query**. This field supports workflow variables through **Insert Variable**. |
| Number of Results | No | Number of results in **Number of results**. |
| Language | No | Language value in **Language**. You can choose from the list or enable **Custom Value**. |
| Language Custom Value | No | Controls whether **Language** uses the built-in list or a custom value. |
| Location | No | Location value in **Location**. You can choose from the list or enable **Custom Value**. |
| Location Custom Value | No | Controls whether **Location** uses the built-in list or a custom value. |
| Fallback Search | No | Enables **Fallback Search** if the primary search fails. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
| Add this step from the **Research** group in **Search steps...**. | | |
The **Search Query** field supports **Insert Variable**. The **Language** and **Location** controls can use the built-in lists or switch to **Custom Value** for manual values or workflow variables.
To inspect supported countries programmatically, use [Search Service Countries](../../../api-reference/overview). Bing Search uses country-name values such as `United States`.
## Output
Click **Run** in the step header to test the step. Fetch Hive shows the search result output in **Output** after the run completes.
Use the variable picker in a later step to insert the exact output path available for that run. The base reference is:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
If you want the full result set, reference the base output directly:
```text theme={null}
{{step_2.output}}
```
Use the variable picker after a test run to inspect any nested fields available from the returned Bing results.
## Example
Add **Bing Search** from the **Research** group in **Search steps...**.
Set **Name** to something like `Search analyst reports`.
Enter your query in **Search Query**. If the query should reuse data from earlier workflow steps, click **Insert Variable** and add that reference.
Choose **Number of results**, then set **Language** and **Location** from the lists or switch either field to **Custom Value**.
Turn **Fallback Search** on if you want a backup service when the primary search fails.
Click **Run** and review the returned search results in **Output** before using them in a later step.
## Notes
* This step uses Bing-specific language and location controls in the editor.
* The **Number of results** control is the same shared results setting pattern used in this part of the workflow editor.
* If you need the exact returned fields for later references, run the step once and inspect the variable picker.
See also: [Creating and Editing](../../creating-and-editing), [Testing and Iteration](../../testing-and-iteration), and [Error Handling](../../error-handling)
# Copilot Search
Source: https://docs.fetchhive.com/workflows/steps/web-research/copilot-search
Configure a workflow step that searches the web with Microsoft Copilot and stores the results for later steps
Use **Copilot Search** when you want a workflow step to search the web with Microsoft Copilot from Fetch Hive and pass the results into later workflow steps.
## Configuration
| Option | Required | Description |
| ------------------------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Search Query | Yes | Query in **Search Query**. This field supports workflow variables through **Insert Variable**. |
| Location | No | Location value in **Location**. You can choose from the list or enable **Custom Value**. |
| Location Custom Value | No | Controls whether **Location** uses the built-in list or a custom value. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
| Add this step from the **Microsoft** group in **Search steps...**. | | |
The **Search Query** field supports **Insert Variable**. The **Location** field can use the built-in list or switch to **Custom Value** when you want to type a value manually or insert a workflow variable.
## Output
Click **Run** in the step header to test the step. Fetch Hive shows the search result output in **Output** after the run completes.
Use the variable picker in a later step to insert the exact output path available for that run. The base reference is:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
If you want the full result set, reference the base output directly:
```text theme={null}
{{step_2.output}}
```
Use the variable picker after a test run to inspect any nested fields available from the returned Copilot results.
## Example
Add **Copilot Search** from the **Microsoft** group in **Search steps...**.
Set **Name** to something like `Find Microsoft ecosystem coverage`.
Enter your query in **Search Query**. If the query should reuse values from earlier workflow steps, click **Insert Variable** and add that reference.
Choose **Location** from the list or switch to **Custom Value** if you want to type a location or insert a variable.
Choose what should happen in **When the step fails**.
Click **Run** and review the returned results in **Output** before using them in a later step.
## Notes
* This step appears under **Microsoft** in the step picker, not under **Research**.
* The editor does not show language, result count, or fallback controls for this step.
* If you need the exact returned fields for later references, run the step once and inspect the variable picker.
See also: [Creating and Editing](../../creating-and-editing), [Testing and Iteration](../../testing-and-iteration), and [Error Handling](../../error-handling)
# Exa Search
Source: https://docs.fetchhive.com/workflows/steps/web-research/exa-search
Configure a workflow step that searches the web with Exa and stores the results for later steps
Use **Exa Search** when you want a workflow step to search the web with Exa and control how much content, filtering, and summarization Fetch Hive returns.
## Configuration
| Option | Required | Description |
| ----------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Search Query | Yes | Query in **Search Query**. This field supports workflow variables through **Insert Variable**. |
| Search Type | No | Search mode in **Search Type**. Available values are `neural`, `keyword`, and `auto`. |
| Number of Results | No | Number of results in **Number of results**. |
| Domain Filter Mode | No | Whether **Domain Filter** should include or exclude the listed domains. |
| Domain Filter | No | Comma-delimited domains in **Domain Filter**. This field supports workflow variables through **Insert Variable**. |
| Text | No | Controls whether result text is included with each result. |
| Max Characters | No | Maximum characters per result when **Text** is enabled. |
| Summary | No | Controls whether result summaries are returned. |
| Summary Query | No | Optional **Summary query** used when **Summary** is enabled. This field supports workflow variables through **Insert Variable**. |
| Charge Type | No | Value selected in **Charge type**. Available values are **Hosted** and **Personal**. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
| Add this step from the **Research** group in **Search steps...**. | | |
The **Search Type** tabs let you choose between **Neural**, **Keyword**, and **Auto**. **Domain Filter** supports both include and exclude modes. Turn **Text** on if you want result content, and turn **Summary** on if you want a summary for each result.
## Output
Click **Run** in the step header to test the step. Fetch Hive shows the Exa result output in **Output** after the run completes.
Use the variable picker in a later step to insert the exact output path available for that run. The base reference is:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
If you want the full result set, reference the base output directly:
```text theme={null}
{{step_2.output}}
```
The exact shape depends on which options you enable. For example, text and summary fields only appear when those features are turned on. Use the variable picker after a test run to inspect the returned fields.
## Example
Add **Exa Search** from the **Research** group in **Search steps...**.
Set **Name** to something like `Find enterprise AI vendors`.
Enter your query in **Search Query**. If the query should reuse workflow data, click **Insert Variable** and add that reference.
Choose **Search Type** based on how specific the search should be, then set **Number of results**.
If you want to narrow the search, add domains in **Domain Filter** and choose **Include** or **Exclude**.
Turn **Text** on if you want content from each result, and set **Maximum characters per result** if needed.
Turn **Summary** on if you want a summary for each result. Add a **Summary query** if the summary should answer a more specific question than the main search.
Choose **Charge type**, click **Run**, and review the returned results in **Output**.
## Notes
* **Domain Filter** accepts comma-delimited base domains and subdomains.
* **Maximum characters per result** only matters when **Text** is enabled.
* **Summary query** is optional. If you leave it blank, Fetch Hive uses the step's existing query context.
See also: [Creating and Editing](../../creating-and-editing), [Testing and Iteration](../../testing-and-iteration), and [Error Handling](../../error-handling)
# Exa Similar
Source: https://docs.fetchhive.com/workflows/steps/web-research/exa-similar
Configure a workflow step that finds pages similar to a source URL and stores the results for later steps
Use **Exa Similar** when you want a workflow step to start from a known URL and find similar pages inside Fetch Hive.
## Configuration
| Option | Required | Description |
| ----------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| URL | Yes | Source URL in **URL**. This field supports workflow variables through **Insert Variable**. |
| Number of Results | No | Number of results in **Number of results**. |
| Domain Filter Mode | No | Whether **Domain Filter** should include or exclude the listed domains. |
| Domain Filter | No | Comma-delimited domains in **Domain Filter**. This field supports workflow variables through **Insert Variable**. |
| Include Phrase | No | Phrase in **Include phrase**. This field supports workflow variables through **Insert Variable**. |
| Exclude Phrase | No | Phrase in **Exclude phrase**. This field supports workflow variables through **Insert Variable**. |
| Text | No | Controls whether result text is included with each result. |
| Max Characters | No | Maximum characters per result when **Text** is enabled. |
| Summary | No | Controls whether result summaries are returned. |
| Summary Query | No | Optional **Summary query** used when **Summary** is enabled. This field supports workflow variables through **Insert Variable**. |
| Charge Type | No | Value selected in **Charge type**. Available values are **Hosted** and **Personal**. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
| Add this step from the **Research** group in **Search steps...**. | | |
This step starts with a source URL instead of a search phrase. You can still narrow the result set with **Domain Filter**, **Include phrase**, and **Exclude phrase**, then optionally turn on **Text** and **Summary**.
## Output
Click **Run** in the step header to test the step. Fetch Hive shows the similar-page result output in **Output** after the run completes.
Use the variable picker in a later step to insert the exact output path available for that run. The base reference is:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
If you want the full result set, reference the base output directly:
```text theme={null}
{{step_2.output}}
```
The exact shape depends on which options you enable. Use the variable picker after a test run to inspect the returned fields.
## Example
Add **Exa Similar** from the **Research** group in **Search steps...**.
Set **Name** to something like `Find similar vendor pages`.
Paste the source page into **URL**. If the URL comes from an earlier step, click **Insert Variable** and add that reference.
Choose **Number of results**, then add an **Include phrase** or **Exclude phrase** if you want to tighten the match.
If you want to limit where results can come from, add domains in **Domain Filter** and choose **Include** or **Exclude**.
Turn **Text** on if you want content from each result, and turn **Summary** on if you want summaries for each result.
Choose **Charge type**, click **Run**, and review the returned similar pages in **Output**.
## Notes
* Use **Exa Similar** when you already have a representative URL and want related pages. Use **Exa Search** when you want to start from a search query instead.
* **Include phrase** and **Exclude phrase** each support a single phrase of up to five words in the current editor guidance.
* **Summary query** is optional. If you leave it blank, Fetch Hive uses the step's existing input context.
See also: [Exa Search](./exa-search), [Creating and Editing](../../creating-and-editing), and [Testing and Iteration](../../testing-and-iteration)
# Google News
Source: https://docs.fetchhive.com/workflows/steps/web-research/google-news
Configure a workflow step that searches Google News and stores article results for later steps
Use **Google News** when you want a workflow step to search recent news coverage from Fetch Hive and pass those results into later workflow steps.
## Configuration
| Option | Required | Description |
| ----------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Search Query | Yes | Query in **Search Query**. This field supports workflow variables through **Insert Variable**. |
| Number of Results | No | Number of results in **Number of results**. |
| Language | No | Language value in **Language**. You can choose from the list or enable **Custom Value**. |
| Language Custom Value | No | Controls whether **Language** uses the built-in list or a custom value. |
| Location | No | Location value in **Location**. You can choose from the list or enable **Custom Value**. |
| Location Custom Value | No | Controls whether **Location** uses the built-in list or a custom value. |
| Fallback Search | No | Enables **Fallback Search** if the primary search fails. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
| Add this step from the **Research** group in **Search steps...**. | | |
The **Search Query** field supports **Insert Variable**. The **Language** and **Location** controls can use the built-in lists or switch to **Custom Value** for manual values or workflow variables.
To inspect supported countries programmatically, use [Search Service Countries](../../../api-reference/overview). Google News uses country-name values such as `United States`.
## Output
Click **Run** in the step header to test the step. Fetch Hive shows the news result output in **Output** after the run completes.
Use the variable picker in a later step to insert the exact output path available for that run. The base reference is:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
If you want the full result set, reference the base output directly:
```text theme={null}
{{step_2.output}}
```
Use the variable picker after a test run to inspect any nested fields available from the returned article results.
## Example
Add **Google News** from the **Research** group in **Search steps...**.
Set **Name** to something like `Track AI regulation coverage`.
Enter a topic in **Search Query**. If the topic should come from an earlier step, click **Insert Variable** and add that reference.
Choose **Number of results**, then set **Language** and **Location** from the lists or switch either field to **Custom Value**.
Turn **Fallback Search** on if you want a backup service when the primary news search fails.
Click **Run** and review the returned article results in **Output** before sending them to a later step such as **AI Prompt**.
## Notes
* Use **Google News** when you care about current coverage or recent articles rather than general web pages.
* **Language** and **Location** can use built-in selectable values or a manual custom value.
* If you need the exact returned fields for later references, run the step once and inspect the variable picker.
See also: [Creating and Editing](../../creating-and-editing), [Testing and Iteration](../../testing-and-iteration), and [Error Handling](../../error-handling)
# Google Search
Source: https://docs.fetchhive.com/workflows/steps/web-research/google-search
Configure a workflow step that searches Google and stores the results for later steps
Use **Google Search** when you want a workflow step to search the web from Fetch Hive and pass the results into later workflow steps.
## Configuration
| Option | Required | Description |
| ----------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Search Query | Yes | Query in **Search Query**. This field supports workflow variables through **Insert Variable**. |
| Number of Results | No | Number of results in **Number of results**. |
| Language | No | Language value in **Language**. You can choose from the list or enable **Custom Value**. |
| Language Custom Value | No | Controls whether **Language** uses the built-in list or a custom value. |
| Location | No | Location value in **Location**. You can choose from the list or enable **Custom Value**. |
| Location Custom Value | No | Controls whether **Location** uses the built-in list or a custom value. |
| Fallback Search | No | Enables **Fallback Search** if the primary search fails. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
| Add this step from the **Research** group in **Search steps...**. | | |
The **Search Query** field supports **Insert Variable**. The **Language** and **Location** controls can use the built-in lists or switch to **Custom Value** when you want to type a value manually or insert a workflow variable.
To inspect supported countries programmatically, use [Search Service Countries](../../../api-reference/overview). Google Search uses country-name values such as `United States`.
## Output
Click **Run** in the step header to test the step. Fetch Hive shows the search result output in **Output** after the run completes.
Use the variable picker in a later step to insert the exact output path available for that run. The base reference is:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
If you want the full result set, reference the base output directly:
```text theme={null}
{{step_2.output}}
```
Use the variable picker after a test run to inspect any nested fields available from the returned search results.
## Example
Add **Google Search** from the **Research** group in **Search steps...**.
Set **Name** to something like `Find competitor pricing`.
Enter your query in **Search Query**. If part of the query comes from an earlier step, click **Insert Variable** and add that reference.
Choose **Number of results**, then set **Language** and **Location** from the lists or switch either field to **Custom Value**.
Turn **Fallback Search** on if you want a backup service when the primary search fails.
Click **Run** and review the returned search results in **Output** before wiring the result into a later step.
## Notes
* **Language** and **Location** can use built-in selectable values or a manual custom value.
* Use **Insert Variable** in **Search Query**, or in custom language and location fields, when the search parameters should come from earlier workflow steps.
* If you need to confirm the exact returned fields for later step references, run the step once and inspect the variable picker.
See also: [Creating and Editing](../../creating-and-editing), [Testing and Iteration](../../testing-and-iteration), and [Error Handling](../../error-handling)
# Perplexity Search
Source: https://docs.fetchhive.com/workflows/steps/web-research/perplexity-search
Search the web with Perplexity's standalone Search API from any workflow
Use **Perplexity Search** when a workflow needs normalized web results from Perplexity's standalone Search API.
This is different from **Sonar Web Search**. Perplexity Search is a workflow step and cross-provider agent tool backed by `POST /search`. Sonar Web Search is native search available only to agents using Perplexity Sonar models.
## Configuration
| Option | Required | Description |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Name | No | Label shown on the workflow canvas. |
| Search Query | Yes | Non-empty query. Use **Insert Variable** to include prior step output. |
| Number of results | No | Maximum results from 1 to 20. The default is 10. |
| Country | No | ISO country restriction. The default is United States; choose **No country restriction** to omit it. |
| Search context size | No | `Low`, `Medium`, or `High` extracted-content preset. The default is `High`. Select **Custom token limits** to omit the preset. |
| Maximum total tokens | No | Total extracted webpage-content limit from 1 to 1,000,000. |
| Maximum tokens per page | No | Per-result-page content limit from 1 to 1,000,000. Setting either token limit omits search context size. |
| Search languages | No | Up to 20 ISO 639-1 language codes selected from the searchable multi-select. |
| Updated after / before | No | Optional last-updated date range. The after date must be earlier than the before date. |
| Published after / before | No | Optional publication date range. The after date must be earlier than the before date. Dates are sent as `MM/DD/YYYY`. |
| Publication recency | No | Past `hour`, `day`, `week`, `month`, or `year`. |
| Credentials | No | **Hosted** uses Fetch Hive's Perplexity connection. **Personal** requires an enabled Perplexity integration in the workspace. |
| When the step fails | No | Terminate the workflow or continue after an error. |
The step supports parallelization. Each version keeps its own query, credential mode, and complete search-option set and performs a separate search call.
## Output
The output is an array of normalized results. Each result can contain:
```json theme={null}
{
"title": "Example result",
"url": "https://example.com/result",
"snippet": "A short result excerpt",
"date": "2026-07-24",
"last_updated": "2026-07-24"
}
```
Optional fields are omitted when Perplexity does not return them. An empty array is a successful, billable search and can be passed directly to an iterator:
```text theme={null}
{{perplexity_search.output}}
```
## Billing and limits
Hosted calls use Perplexity's fixed Search API request cost. Personal calls use one platform task and your workspace integration. Each actual request consumes one provider-tool limit unit; validation failures do not.
See also: [Workflow step overview](../overview), [Error Handling](../../error-handling), and [Perplexity Search for agents](../../../agents/mcp-tools/perplexity-search-api)
# RSS Feed
Source: https://docs.fetchhive.com/workflows/steps/web-research/rss-feed
Configure a workflow step that fetches entries from a direct RSS or Atom feed URL
Use **RSS Feed** when you want a workflow to read entries from a direct RSS or Atom feed URL and pass those entries to later steps.
The step only reads the feed document. It does not discover feeds from a website URL, and it does not scrape article pages. To fetch the article content for each feed entry, send the feed output into an **Iteration** step and use **Website Scrape** inside the loop.
## Configuration
| Option | Required | Description |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| Feed URL | Yes | Direct RSS or Atom feed URL. This field supports workflow variables through **Insert Variable**. |
| Item Limit | No | Maximum number of feed entries to return. Defaults to `10`. Valid range is `1` to `100`. |
| New items only | No | When enabled, repeated scheduled or deployed runs suppress feed items this workflow scope has already emitted. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
Add this step from the **Research** group in **Search steps...**.
## Output
The step returns normalized feed metadata plus an `items` array:
```json theme={null}
{
"feed": {
"title": "Example Feed",
"url": "https://example.com/feed.xml",
"description": "Latest posts"
},
"items": [
{
"id": "stable-item-id",
"guid": "post-123",
"title": "Post title",
"url": "https://example.com/posts/post-title",
"summary": "Entry summary",
"author": "Author name",
"published_at": "2026-06-03T12:00:00Z",
"categories": ["News"],
"source_url": "https://example.com/feed.xml"
}
]
}
```
Use these workflow variables in later steps:
```text theme={null}
{{rss_step.output.feed}}
{{rss_step.output.items}}
```
For an **Iteration** step on a **single** (non-parallel) RSS feed, set **Iterator** to:
```text theme={null}
{{rss_step.output.items}}
```
Inside the iteration body, use each entry's URL with the **Iteration step's own identifier** (for example `step_5` if that is the Iteration), not a literal `iteration`:
```text theme={null}
{{step_5.item.url}}
```
### Parallelized RSS feeds
When **Parallelization** is enabled on the RSS step (multiple feed URL variants), the step output becomes an **ordered array** of feed objects — one per successful version. In that case:
* `{{rss_step.output.items}}` resolves to **null** (a bare field name on an array is invalid).
* `{{rss_step.output.*.items}}` plucks each variant's `items` array and yields an **array of arrays**. The `*` wildcard does not flatten.
* To scrape every article across all feeds, add a **Data Transform** step with mode **Flatten array** and source `{{rss_step.output.*.items}}`, then set the Iteration iterator to `{{flatten_step.output}}`.
## Example: summarize new feed articles
Create this workflow:
```text theme={null}
RSS Feed -> Iteration -> Website Scrape -> AI Prompt -> Aggregate/output
```
1. Add **RSS Feed** and set **Feed URL** to the direct feed URL.
2. Set **Item Limit** to the number of entries you want per run.
3. Leave **New items only** enabled for scheduled or repeated deployed runs.
4. Add **Iteration** and set **Iterator** to `{{rss_step.output.items}}` (single feed). For parallelized feeds, flatten first as described above.
5. Inside the iteration body, add **Website Scrape** and set **URL** to `{{iteration_step.item.url}}` using the Iteration step's identifier.
6. Add an **AI Prompt** after the scrape step to summarize the article content.
7. Aggregate or return the summaries from the workflow output.
## Notes
* RSS and Atom feed URLs are supported. Website feed discovery is not part of this step.
* The step normalizes relative item URLs to absolute URLs when the feed URL can be used as a base.
* Dedupe is lightweight seen-item suppression for repeated runs. It is not a feed history or replay interface.
* Article scraping and summarization are separate steps so you can control crawl settings, prompts, and aggregation explicitly.
See also: [Website Scrape](website-scrape), [Testing and Iteration](../../testing-and-iteration), and [Scheduled Deployments](../../scheduled-deployments)
# Website Scrape
Source: https://docs.fetchhive.com/workflows/steps/web-research/website-scrape
Configure a workflow step that scrapes a website URL and returns selected content types for later steps
Use **Website Scrape** when you want a workflow step to fetch a page from the web and return the parts of that page your workflow needs.
## Configuration
| Option | Required | Description |
| ----------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| Name | No | Label for the step in the workflow canvas. |
| URL | Yes | URL in **URL**. This field supports workflow variables through **Insert Variable**. |
| HTML Output | No | Controls whether **HTML** output is returned. |
| Markdown Output | No | Controls whether **Markdown** output is returned. |
| Links Output | No | Controls whether extracted **Links** are returned. |
| Subpages | No | Controls whether **Subpages** crawling is enabled. |
| Crawl Mode | No | Crawl behavior selected in **Crawl Mode**. |
| Max Characters | No | Maximum output size set in **Max Characters**. |
| Max Retries | No | Retry count in **Max Retries**. |
| Timeout (ms) | No | Timeout value in **Timeout (ms)**. |
| Screenshot | No | Controls whether a page screenshot is captured. |
| Screenshot Type | No | Screenshot mode in **Screenshot Type** when screenshots are enabled. |
| When the step fails | No | Controls whether the workflow should **Terminate Workflow** or **Continue** if this step fails. |
| Add this step from the **Research** group in **Search steps...**. | | |
The **URL** field supports **Insert Variable**. Below that, the settings sheet lets you choose which output types to return: **HTML**, **Markdown**, **Links**, and **Subpages**.
Use **Crawl Mode** to control how Fetch Hive retrieves the page:
* **Preferred** tries a live crawl first, then falls back to cache.
* **Always** always uses a live crawl.
* **Fallback** uses cache first, then crawls if needed.
* **Never** only uses cache.
If you turn **Screenshot** on, **Screenshot Type** appears with **Viewport** and **Full Page** options.
## Output
Click **Run** in the step header to test the step. Fetch Hive shows the scrape result in **Output** after the run completes.
Use the variable picker in a later step to insert the exact output path available for that run. The base reference is:
```text theme={null}
{{STEP_IDENTIFIER.output}}
```
The exact fields depend on which outputs you enabled. For example, HTML, markdown, links, subpage data, and screenshot-related fields only appear when those outputs are turned on. Use the variable picker after a test run to inspect the returned fields.
## Example
Add **Website Scrape** from the **Research** group in **Search steps...**.
Set **Name** to something like `Scrape product page`.
Paste the page into **URL**. If the URL comes from an earlier workflow step, click **Insert Variable** and add that reference.
Turn on the outputs you need. For example, enable **Markdown** for clean content, **Links** for extracted links, and **Subpages** if you want one subpage crawled from the main page.
Choose a **Crawl Mode**, then set **Max Characters**, **Max Retries**, and **Timeout (ms)** for the run.
If you need a visual capture, turn **Screenshot** on and choose **Viewport** or **Full Page** in **Screenshot Type**.
Click **Run** and review the scraped result in **Output** before sending it to later workflow steps.
## Notes
* The returned result depends on which output toggles you enable, so inspect the variable picker after a run if you need exact field names.
* The editor shows a warning for direct LinkedIn URLs. LinkedIn URLs are not supported for scraping.
* Use **Markdown** when you want cleaner page content, **HTML** when you need raw markup, and **Links** when you only need extracted URLs.
See also: [Creating and Editing](../../creating-and-editing), [Testing and Iteration](../../testing-and-iteration), and [Error Handling](../../error-handling)
# Testing and Iteration
Source: https://docs.fetchhive.com/workflows/testing-and-iteration
Test workflows in the editor, work with Run History and Output, and iterate before creating a workflow deployment
Use the editor run flow to check a workflow before you save a version or create a workflow deployment. The workflow editor separates in-dashboard testing from live invocation, so you can iterate on steps and inputs without publishing changes first.
## Overview
Workflow testing in the editor is centered around **Run Workflow**, **Live Progress**, and **Start a new Workflow Run**. The run sheet shows step progress and output for the workflow run that is currently active.
You can also run an individual step from the canvas when you want a smaller test while you are still editing the workflow.
## How do I start a workflow run in the editor?
Open the workflow in the editor.
Click **Run Workflow** in the bottom control bar.
This opens **Live Progress**. It does not start the workflow by itself.
In **Live Progress**, click **Start**.
Fetch Hive opens **Start a new Workflow Run**. Click **Start Workflow Run** to begin the run.
If your **Start** step has inputs, the modal shows a field for each variable so you can enter test values before the run starts. **Array** start inputs use a JSON textarea and must contain a valid JSON array before the run can start.
Use the sample input actions next to a start input when you want to load a saved test value or save the current value for later runs.
If a Start input has an **Example value**, the example only helps you build the workflow in the editor. The run modal still requires the real value you want to test; examples are not copied into the run.
## Where do I see results from a workflow run?
After the run starts, keep **Live Progress** open.
Use the **Progress** tab to review step completions for the active run. Running completions can appear before they finish, so this tab is useful while the workflow is still executing. Expand a completed step to see its output without waiting for the rest of the workflow to finish.
Use the **Output** tab to inspect the active workflow run's current output.
The output view can render different result types. In the reviewed UI, image outputs render as images, PDF outputs render as a download link, and other results render directly in the sheet.
If no output is available yet, the sheet shows a waiting state while the run is active. After the active run finishes, the sheet keeps that run visible so you can review its final step results and output. Use workflow logs for older run history.
If a workflow reaches a **Human in the Loop** step, the run is paused while it waits for the recipient's choice. Paused runs do not occupy **Live Progress**, so you can start another editor test run while the human choice is pending. Open the paused run from workflow logs to see why it is waiting and to access the choice page.
## How do I test start inputs and repeat runs while iterating?
Define your variables on **Start** first.
Each time you open **Start a new Workflow Run**, Fetch Hive uses those **Start** inputs to build the run form. Text inputs accept plain text, while array inputs accept JSON arrays such as `["one", "two"]`.
Load a saved sample input when you want to restore a known test case quickly. Save the current value as a sample input when you want to reuse it in later workflow runs or prompt tests.
Use array examples on the **Start** step when you want to configure an **Iteration** before the source input has ever been submitted. The editor can preview the first example item and expose its fields for variable insertion, but each run still uses the array you enter in the run form.
Change the input values in the modal when you want to test the same workflow against a different case without changing the workflow structure itself.
This is the safest way to repeat runs while you are tuning prompt content, step settings, or failure behavior.
## How do I test a single step while I edit?
Hover over a step node on the canvas.
Click **Run Step** to start a test for that step.
For **AI Prompt** steps, the step settings header also includes **Run**, and the right side of the sheet shows the prompt messages and model response for that step test. After a successful sheet **Run**, the assistant response is also saved as that step's editor sample output, so the variable picker can offer `{{STEP_IDENTIFIER.output}}` (and nested fields) to later steps without waiting for a full workflow run or canvas **Run Step**.
Use step tests for quicker iteration when you do not need to run the full workflow every time.
Single-step tests resolve variables from the active workflow run when one exists. If a Start input has no real run value yet, the step test can use that input's **Example value** as an editor-only fallback, including indexed array paths such as `{{feeds.0.url}}` or wildcard paths such as `{{feeds.*.url}}`.
## What do the editor save states mean while I test?
The workflow editor header can show transient save states such as editing, saving, and saved while you change step settings.
Treat these as editor state indicators, not version checkpoints. Your changes can be saved in the editor without being saved as a named workflow version yet.
Use **Save Version** in the bottom control bar when you are happy with the workflow state you just tested and want a checkpoint you can compare or deploy later.
See also: [Creating and Editing](./creating-and-editing) and [Publishing and Versioning](./publishing-and-versioning)
# Airtable
Source: https://docs.fetchhive.com/agents/mcp-tools/airtable
Give an agent access to your connected Airtable account so it can create, list, update, and retrieve records
Airtable gives your agent access to your connected Airtable base. The agent can create records, list and filter records, update existing records, and retrieve individual records while it responds to chat messages or completes tasks.
## What it does
When Airtable is enabled on an agent, the agent can automatically perform Airtable actions as part of its reasoning process. You ask a question or give it a task — the agent decides when and how to use Airtable on your behalf.
## Prerequisites
You must have an active Airtable connection in your workspace before enabling this tool. If no active connection exists, the toggle is disabled.
1. Go to **Integrations** for your workspace.
2. Find **Airtable** in the integrations grid.
3. Click **Connect** and complete the OAuth flow.
4. Return to your agent and enable the tool.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **Airtable**. The Airtable node appears on the canvas.
4. Click the node to open the **Settings** panel on the right.
5. In the **Authentication** field, select the connected Airtable account the agent should use.
6. If no active connection is found, the settings panel shows a warning with a link to **Integrations** to connect first.
## Use cases
* Create a new Airtable record when a workflow completes or a user makes a request.
* Search your Airtable base for records matching user-provided criteria.
* Update an existing record when the status of a task changes.
## Notes
* The agent uses your connected Airtable account to perform actions. Make sure the OAuth connection has appropriate access to the bases and tables your workflows need.
* This tool counts as 1 credit per action the agent performs.
See also: [Integrations](../../workspace/integrations), [Creating and Configuring](../creating-and-configuring)
# Anthropic Web Search
Source: https://docs.fetchhive.com/agents/mcp-tools/anthropic-web-search
Let a Claude-powered agent search the public web using Anthropic's native web search tool
Anthropic Web Search gives your agent access to live public web search when it is powered by an Anthropic Claude model.
## What it does
This tool lets a Claude agent look up current information on the web while it responds. It uses Anthropic's native `web_search` server tool, so no separate MCP server is required.
## Requirements
Anthropic Web Search is only available when your agent is configured to use an **Anthropic** model. Your Anthropic organization must also have web search enabled in Anthropic's console.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Make sure the agent's model is set to an Anthropic Claude model.
3. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
4. In **MCP Tools**, click **Anthropic Web Search**.
## Configuration
Anthropic Web Search has two settings:
* **Max Uses**: the maximum number of Anthropic web search requests the model may perform during a single response. The default is `3`, and the maximum is `20`.
* **Location Country**: a two-letter country code used to localize search results. The default is `US`. FetchHive sends this as Anthropic's approximate `user_location.country`.
Hive Agent runs can override **Location Country** from **Start Run** → **Search country** for that execution.
FetchHive sends Anthropic's `web_search_20260209` server tool and Anthropic handles search execution and citations.
## Use cases
* Look up current events or recent news using a Claude agent.
* Check live web sources before the agent answers a question.
* Ground agent responses with cited public web sources.
## Notes
* This tool is powered by Anthropic's native `web_search` capability, not an external MCP server.
* Search calls are billed as Anthropic web search requests in addition to normal model token usage.
* Use this tool's **Max Uses** setting to limit native web search calls.
* Use **Chat** in the editor to see when the agent calls **Anthropic Web Search** during a test run. See [Testing with Chat](../testing-with-chat).
# File Tools
Source: https://docs.fetchhive.com/agents/mcp-tools/file-tools
Understand how agents read attachments and create generated files
`file_tools` is a Fetch Hive system MCP tool that is added to every agent automatically. It cannot be disabled or removed. Fetch Hive attaches the provider-facing file tools to a run only when the turn has document attachments, history file context, or asks to generate or export a file.
Uploaded CSV, XLSX, PDF, DOCX, text, and Markdown attachments are exposed to the agent as an `` manifest. The agent should call `read_file` before relying on document contents. `read_file` can only access URLs that were supplied as structured attachments in the current request or conversation history.
Public API callers can pass attachments as HTTPS URL strings or as objects with
`file_url`, `file_name`, and `file_type`. URL strings are enough for most
calls; Fetch Hive infers metadata from the URL when it can.
When the current turn asks to generate or export a file, agents can call `write_file` to create PDF, DOCX, XLSX, or CSV files. For PDF and DOCX files, markdown content is recommended and preserves common document structure such as headings, paragraphs, lists, emphasis, code blocks, blockquotes, horizontal rules, and simple tables. For CSV files, provide CSV or JSON tabular content (`input_format` `csv` or `json`; JSON uses a single sheet). Generated files are stored as workspace assets and returned with a time-limited `file_url` (plus `file_url_expires_at` and asset `id`). Use the asset `id` with the assets API if you need a fresh download URL later. File tool calls are recorded in traces and completions as `read_file` and `write_file` sources.
When a Hive Agent run asks for a downloadable table or document, Fetch Hive produces the file after compose and attaches it to the run alongside the text final response (asset id, URL, name, and type). Retrying compose reuses already-verified node work without re-running the plan/execute/verify loop.
In a saved Agent chat, generated and uploaded files stay available in **Use from this chat**, even after older messages are summarized. Choosing one reuses the existing Asset without uploading it again. File contents are still read only when the Agent needs them.
# Google Docs
Source: https://docs.fetchhive.com/agents/mcp-tools/google-docs
Give an agent access to your connected Google Docs account so it can create, search, copy, and update documents
Google Docs gives your agent access to your connected documents. The agent can create documents, copy existing files, search by title, and insert or replace text while it responds to chat messages or completes tasks.
## What it does
When Google Docs is enabled on an agent, the agent can automatically perform document actions as part of its reasoning process. You ask a question or give it a task — the agent decides when and how to use your Google Docs account on your behalf.
## Prerequisites
You must have an active Google Docs connection in your workspace before enabling this tool. If no active connection exists, the toggle is disabled.
1. Go to **Integrations** for your workspace.
2. Find **Google Docs** in the integrations grid.
3. Click **Connect** and complete the OAuth flow.
4. Return to your agent and enable the tool.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **Google Docs**. The Google Docs node appears on the canvas.
4. Click the node to open the **Settings** panel on the right.
5. In the **Authentication** field, select the connected Google Docs account the agent should use.
6. If no active connection is found, the settings panel shows a warning with a link to **Integrations** to connect first.
## Use cases
* Create a document from a workflow summary or prompt output.
* Copy a template document and fill in new title or body text.
* Search for a document by name and retrieve its contents.
* Insert text into an existing document when a later step produces new content.
## Notes
* The agent uses your connected Google Docs account to perform actions. Make sure the OAuth connection has access to the documents your workflows need.
* This tool counts as 1 credit per action the agent performs.
* OAuth may show third-party authorization branding during the connect flow.
* If a previous connection stops working, reconnect Google Docs in **Integrations**, then select the new account on the tool node.
See also: [Integrations](../../workspace/integrations), [Creating and Configuring](../creating-and-configuring)
# Google Maps
Source: https://docs.fetchhive.com/agents/mcp-tools/google-maps
Give an agent access to your connected Google Maps account so it can geocode addresses, search places, and calculate routes
Google Maps gives your agent access to Google's location APIs. The agent can geocode addresses, search for places, retrieve place details, calculate routes, and look up time zones when you ask it to.
## What it does
When Google Maps is enabled on an agent, the agent can automatically call Google Maps APIs as part of its reasoning process. You ask a question or give it a task — the agent decides when and how to use your connected account.
## Prerequisites
You must have an active Google Maps connection in your workspace before enabling this tool. If no active connection exists, the tool cannot be added.
1. Go to **Integrations** for your workspace.
2. Find **Google Maps** in the integrations grid.
3. Click **Connect** and complete the OAuth flow.
4. Return to your agent and enable the tool.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **Google Maps**. The Google Maps node appears on the canvas.
4. Click the node to open the **Settings** panel on the right.
5. In the **Authentication** field, select the connected Google Maps account the agent should use.
6. If no active connection is found, the settings panel shows a warning with a link to **Integrations** to connect first.
## Available actions
Agents can use non-destructive Google Maps actions exposed for your connected account, including:
* Text Search and Nearby Search
* Geocoding API and reverse geocoding actions
* Get Place Details and Autocomplete
* Get Route, Get Direction, and Compute Route Matrix
* Get Time Zone and Embed Google Map
Google Maps is also available as a **workflow step** for curated location lookups in pipelines.
## Use cases
* Convert a customer address into coordinates for a downstream workflow step.
* Search for restaurants or stores near a location and summarize the results.
* Calculate driving distance and duration between two addresses.
* Look up the time zone for a city before scheduling a meeting.
## Notes
* The agent uses your connected Google Maps account. Google Maps API quotas and billing apply to agent actions the same as direct API usage.
* This tool counts as 1 credit per action the agent performs.
* OAuth may show third-party authorization branding during the connect flow.
See also: [Integrations](../../workspace/integrations), [Creating and Configuring](../creating-and-configuring)
# Google Sheets
Source: https://docs.fetchhive.com/agents/mcp-tools/google-sheets
Give an agent access to your connected Google Sheets account so it can create, search, read, and update spreadsheets
Google Sheets gives your agent access to your connected spreadsheets. The agent can create spreadsheets, search files, read values, and append or update rows while it responds to chat messages or completes tasks.
## What it does
When Google Sheets is enabled on an agent, the agent can automatically perform spreadsheet actions as part of its reasoning process. You ask a question or give it a task — the agent decides when and how to use your Google Sheets account on your behalf.
## Prerequisites
You must have an active Google Sheets connection in your workspace before enabling this tool. If no active connection exists, the toggle is disabled.
1. Go to **Integrations** for your workspace.
2. Find **Google Sheets** in the integrations grid.
3. Click **Connect** and complete the OAuth flow.
4. Return to your agent and enable the tool.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **Google Sheets**. The Google Sheets node appears on the canvas.
4. Click the node to open the **Settings** panel on the right.
5. In the **Authentication** field, select the connected Google Sheets account the agent should use.
6. If no active connection is found, the settings panel shows a warning with a link to **Integrations** to connect first.
## Use cases
* Create a spreadsheet from structured workflow output.
* Search for a spreadsheet by name and read its sheet names.
* Append new rows after a workflow collects form responses.
* Update values in an existing range when a report is refreshed.
## Notes
* The agent uses your connected Google Sheets account to perform actions. Make sure the OAuth connection has access to the spreadsheets your workflows need.
* This tool counts as 1 credit per action the agent performs.
* OAuth may show third-party authorization branding during the connect flow.
* If a previous connection stops working, reconnect Google Sheets in **Integrations**, then select the new account on the tool node.
See also: [Integrations](../../workspace/integrations), [Creating and Configuring](../creating-and-configuring)
# Google Analytics
Source: https://docs.fetchhive.com/agents/mcp-tools/google_analytics
Give an agent access to your connected Google Analytics account so it can query GA4 reports and property metadata
Google Analytics gives your agent access to your connected GA4 properties. The agent can check dimension/metric compatibility and look up property and account metadata while it responds to chat messages or completes tasks.
## What it does
When Google Analytics is enabled on an agent, the agent can automatically query analytics data as part of its reasoning process. You ask a question or give it a task — the agent decides when and how to use your analytics account on your behalf.
## Prerequisites
You must have an active Google Analytics connection in your workspace before enabling this tool. If no active connection exists, the toggle is disabled.
1. Go to **Integrations** for your workspace.
2. Find **Google Analytics** in the integrations grid.
3. Click **Connect** and complete the OAuth flow.
4. Return to your agent and enable the tool.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **Google Analytics**. The Google Analytics node appears on the canvas.
4. Click the node to open the **Settings** panel on the right.
5. In the **Authentication** field, select the connected Google Analytics account the agent should use.
6. If no active connection is found, the settings panel shows a warning with a link to **Integrations** to connect first.
## Available actions
Agents can use all enabled Google Analytics actions, including:
* Get Metadata
* Check Compatibility
* List Account Summaries
* List Property
* Get Property
* Run Report
* Run Realtime Report
* Batch Run Reports
Workflows intentionally expose only the curated metadata/discovery subset. Report actions are available to agents but not workflow steps.
## Use cases
* Pull traffic, acquisition, and engagement reports for the last 30 days.
* Discover valid dimensions and metrics before building a custom report.
* List GA4 accounts and properties to confirm the agent is targeting the right resource.
* Retrieve property details for validation or setup workflows.
## Notes
* The agent uses your connected Google Analytics account to perform actions. Make sure the OAuth connection has access to the properties your workflows need.
* This tool counts as 1 credit per action the agent performs.
* OAuth may show third-party authorization branding during the connect flow.
See also: [Integrations](../../workspace/integrations), [Creating and Configuring](../creating-and-configuring)
# Google Ads
Source: https://docs.fetchhive.com/agents/mcp-tools/googleads
Give an agent access to your connected Google Ads account so it can query campaigns, run GAQL reports, and manage audiences
Google Ads gives your agent access to your connected ad accounts. The agent can list accessible customers, query campaign performance with GAQL, inspect campaigns and customer lists, and perform account updates when you ask it to.
## What it does
When Google Ads is enabled on an agent, the agent can automatically call Google Ads APIs as part of its reasoning process. You ask a question or give it a task — the agent decides when and how to use your ad account on your behalf.
## Prerequisites
You must have an active Google Ads connection in your workspace before enabling this tool. If no active connection exists, the tool cannot be added.
1. Go to **Integrations** for your workspace.
2. Find **Google Ads** in the integrations grid.
3. Click **Connect** and complete the OAuth flow.
4. Return to your agent and enable the tool.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **Google Ads**. The Google Ads node appears on the canvas.
4. Click the node to open the **Settings** panel on the right.
5. In the **Authentication** field, select the connected Google Ads account the agent should use.
6. If no active connection is found, the settings panel shows a warning with a link to **Integrations** to connect first.
## Available actions
Agents can use non-destructive Google Ads actions exposed for your connected account, including:
* List Accessible Customers
* List Sub Accounts
* Get Campaign By Id
* Get Campaign By Name
* Get Customer Lists
* Search Stream GAQL
* Create or update campaigns, ad groups, budgets, assets, and customer lists when prompted
Google Ads is an **agent-only** integration — it does not appear as a workflow step.
## Use cases
* Pull campaign performance for the last 7 or 30 days with a GAQL query.
* List accessible ad accounts before targeting a manager (MCC) child account.
* Look up a campaign by name or ID for validation or reporting.
* Add contacts to a customer list or pause campaigns when you describe the change in chat.
## Notes
* The agent uses your connected Google Ads account. Make sure OAuth access covers the customer IDs you expect the agent to use.
* Manager-account (MCC) setups may require targeting a child customer ID while passing the manager ID as login context; reconnecting alone does not fix permission errors against the wrong account.
* Google Ads API rate limits apply to agent actions the same as direct API usage.
* This tool counts as 1 credit per action the agent performs.
* OAuth may show third-party authorization branding during the connect flow.
See also: [Integrations](../../workspace/integrations), [Creating and Configuring](../creating-and-configuring)
# Google Calendar
Source: https://docs.fetchhive.com/agents/mcp-tools/googlecalendar
Give an agent access to your connected Google Calendar account so it can create, list, find, and manage events
Google Calendar gives your agent access to your connected calendars. The agent can create events, list upcoming meetings, find events, check availability, and update existing events while it responds to chat messages or completes tasks.
## What it does
When Google Calendar is enabled on an agent, the agent can automatically perform calendar actions as part of its reasoning process. You ask a question or give it a task — the agent decides when and how to use your calendar on your behalf.
## Prerequisites
You must have an active Google Calendar connection in your workspace before enabling this tool. If no active connection exists, the toggle is disabled.
1. Go to **Integrations** for your workspace.
2. Find **Google Calendar** in the integrations grid.
3. Click **Connect** and complete the OAuth flow.
4. Return to your agent and enable the tool.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **Google Calendar**. The Google Calendar node appears on the canvas.
4. Click the node to open the **Settings** panel on the right.
5. In the **Authentication** field, select the connected Google Calendar account the agent should use.
6. If no active connection is found, the settings panel shows a warning with a link to **Integrations** to connect first.
## Use cases
* Create a calendar event when a workflow completes or a user makes a booking request.
* List upcoming meetings for the next day or week.
* Find free time slots before scheduling a follow-up.
* Update an event when meeting details change.
## Notes
* The agent uses your connected Google Calendar account to perform actions. Make sure the OAuth connection has access to the calendars your workflows need.
* This tool counts as 1 credit per action the agent performs.
* OAuth may show third-party authorization branding during the connect flow.
See also: [Integrations](../../workspace/integrations), [Creating and Configuring](../creating-and-configuring)
# GPT Search
Source: https://docs.fetchhive.com/agents/mcp-tools/gpt-search
Add GPT Search to an agent and control its search context size and location
GPT Search gives your agent GPT-powered web search in the Fetch Hive editor.
## What it does
This tool helps an agent search the web while using GPT Search settings from the editor. Use it when you want broader web research with control over how much context the search returns and which country it targets.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **GPT Search**.
After you add the tool, select the **GPT Search** node to open its settings sheet.
## Configuration
GPT Search exposes two configuration fields in the settings sheet.
| Option | Description |
| -------------------- | ------------------------------------------------------------------------------------------------- |
| **Context Size** | Controls how much search context Fetch Hive returns to the agent. The default is **Medium**. |
| **Location Country** | Targets the search to a supported country in the settings list. The default is **United States**. |
Hive Agent runs can override **Location Country** from **Start Run** → **Search country** for that execution.
1. Select the **GPT Search** node in the editor.
2. Set **Context Size** to **Low**, **Medium**, or **High**.
3. Set **Location Country** to the country you want to target.
Fetch Hive currently shows these countries in **Location Country**:
* **Albania**
* **Algeria**
* **Afghanistan**
* **Aland Islands**
* **Andorra**
* **Angola**
* **Antigua and Barbuda**
* **Argentina**
* **Armenia**
* **Aruba**
* **Australia**
* **Austria**
* **Azerbaijan**
* **Bahamas**
* **Bahrain**
* **Bangladesh**
* **Barbados**
* **Belgium**
* **Belize**
* **Bermuda**
* **Benin**
* **Bhutan**
* **Bolivia**
* **Bosnia and Herzegovina**
* **Botswana**
* **Brazil**
* **Brunei**
* **Bulgaria**
* **Burkina Faso**
* **Burundi**
* **Cabo Verde**
* **Cambodia**
* **Cameroon**
* **Canada**
* **Cayman Islands**
* **Central African Republic**
* **Chad**
* **Chile**
* **Colombia**
* **Comoros**
* **Congo (Brazzaville)**
* **Congo (DRC)**
* **Costa Rica**
* **Cote d'Ivoire**
* **Croatia**
* **Cyprus**
* **Czechia (Czech Republic)**
* **Denmark**
* **Djibouti**
* **Dominica**
* **Dominican Republic**
* **Ecuador**
* **Egypt**
* **El Salvador**
* **Equatorial Guinea**
* **Eritrea**
* **Estonia**
* **Eswatini (Swaziland)**
* **Ethiopia**
* **Faroe Islands**
* **Fiji**
* **Finland**
* **France**
* **French Guiana**
* **French Polynesia**
* **French Southern Territories**
* **Gabon**
* **Gambia**
* **Georgia**
* **Germany**
* **Ghana**
* **Greece**
* **Grenada**
* **Greenland**
* **Guatemala**
* **Guadeloupe**
* **Guinea**
* **Guinea-Bissau**
* **Guyana**
* **Haiti**
* **Holy See (Vatican City)**
* **Honduras**
* **Hungary**
* **Iceland**
* **India**
* **Indonesia**
* **Iraq**
* **Ireland**
* **Israel**
* **Italy**
* **Jamaica**
* **Japan**
* **Jordan**
* **Kazakhstan**
* **Kenya**
* **Kiribati**
* **Kuwait**
* **Kyrgyzstan**
* **Laos**
* **Latvia**
* **Lebanon**
* **Lesotho**
* **Liberia**
* **Libya**
* **Liechtenstein**
* **Lithuania**
* **Luxembourg**
* **Madagascar**
* **Malawi**
* **Malaysia**
* **Maldives**
* **Mali**
* **Malta**
* **Marshall Islands**
* **Martinique**
* **Mauritania**
* **Mauritius**
* **Mayotte**
* **Mexico**
* **Micronesia**
* **Moldova**
* **Monaco**
* **Mongolia**
* **Montenegro**
* **Morocco**
* **Mozambique**
* **Myanmar**
* **Namibia**
* **Nauru**
* **Nepal**
* **Netherlands**
* **New Caledonia**
* **New Zealand**
* **Nicaragua**
* **Niger**
* **Nigeria**
* **North Macedonia**
* **Norway**
* **Oman**
* **Pakistan**
* **Palau**
* **Palestine**
* **Panama**
* **Papua New Guinea**
* **Paraguay**
* **Peru**
* **Philippines**
* **Poland**
* **Portugal**
* **Qatar**
* **Reunion**
* **Romania**
* **Rwanda**
* **Saint Barthelemy**
* **Saint Helena**
* **Saint Kitts and Nevis**
* **Saint Lucia**
* **Saint Martin (French part)**
* **Saint Pierre and Miquelon**
* **Saint Vincent and the Grenadines**
* **Samoa**
* **San Marino**
* **Sao Tome and Principe**
* **Saudi Arabia**
* **Senegal**
* **Serbia**
* **Seychelles**
* **Sierra Leone**
* **Singapore**
* **Slovakia**
* **Slovenia**
* **Solomon Islands**
* **Somalia**
* **South Africa**
* **South Korea**
* **South Sudan**
* **Spain**
* **Sri Lanka**
* **Suriname**
* **Sweden**
* **Switzerland**
* **Sudan**
* **Svalbard and Jan Mayen**
* **Taiwan**
* **Tajikistan**
* **Tanzania**
* **Thailand**
* **Timor-Leste (East Timor)**
* **Togo**
* **Tonga**
* **Trinidad and Tobago**
* **Tunisia**
* **Turkey**
* **Turkmenistan**
* **Tuvalu**
* **Uganda**
* **Ukraine (with certain exceptions)**
* **United Arab Emirates**
* **United Kingdom**
* **United States of America**
* **Uruguay**
* **Uzbekistan**
* **Vanuatu**
* **Vietnam**
* **Wallis and Futuna**
* **Yemen**
* **Zambia**
* **Zimbabwe**
## Use cases
* Run broader web research before the agent answers.
* Target search behavior to a specific country.
* Give the agent more or less search context depending on the task.
## Notes
* Use [Testing with Chat](../testing-with-chat) to see when the agent calls **GPT Search** during a conversation.
* To add or remove tools from an agent, see [Creating and Configuring](../creating-and-configuring).
# Image Generation
Source: https://docs.fetchhive.com/agents/mcp-tools/image-generation
Let an agent generate images on demand using OpenAI, xAI, or Gemini image generation
Image Generation lets your agent create images from text prompts during a conversation or workflow run.
## What it does
This tool lets an agent call a native `create_image` function. Fetch Hive executes the function server-side against the image generation service, which avoids remote MCP timeout limits for long-running image jobs. The API used depends on the agent's primary provider:
* **OpenAI agents** — routes to OpenAI's image generation API (`gpt-image-2`). Fetch Hive forces agent image size and quality to `auto` to control hosted LLM credit usage.
* **xAI agents** — routes to Grok Imagine (`grok-imagine-image-quality`). OpenAI-only options (size, quality, background, etc.) are ignored.
* **Gemini agents** — routes hosted requests through the Gemini Interactions API in `fetch-image-mcp`. Configure the image model and resolution in the Image Generation tool settings (Gemini agents only). Personal/BYOK Gemini image generation is not supported yet. OpenAI-only options are ignored.
* **Other personal agents** — route image generation through the workspace OpenAI provider key.
When enabled, the agent can generate one or more images at runtime and return them as permanent asset URLs.
Supports both **hosted** and **personal** billing models:
* **Hosted** — images are billed against your workspace's hosted LLM credit balance (no API key required).
* **Personal** — your workspace's own provider key is used and charged directly. OpenAI and xAI agents use their matching provider key; other personal agent providers use the workspace OpenAI key for images. Gemini personal image generation is not supported yet.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **Image Generation**.
After you add the tool, select the **Image Generation** node to open its settings sheet.
## Configuration
| Option | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Billing** | `hosted` uses Fetch Hive managed provider credentials and hosted LLM wallet checks; `personal` uses your workspace provider key and skips hosted-wallet precheck |
| **Image Model** | Gemini agents only. Choose from hosted Gemini image models (`gemini-2.5-flash-image`, `gemini-3.1-flash-lite-image`, `gemini-3.1-flash-image`, `gemini-3-pro-image`). Default: `gemini-2.5-flash-image`. |
| **Resolution** | Gemini 3 image models only. `1K` default; `gemini-3.1-flash-image` also supports `0.5K`, `2K`, and `4K`. |
## Available options (exposed to the agent)
The agent controls these parameters when calling the tool:
| Parameter | Description | Default |
| --------------- | ------------------------------------------------ | -------- |
| `prompt` | Text description of the desired image | Required |
| `n` | Number of images to generate (1–10) | 1 |
| `size` | `1024x1024`, `1536x1024`, `1024x1536`, or `auto` | auto |
| `quality` | `high`, `medium`, or `low` | medium |
| `output_format` | `png`, `jpeg`, or `webp` | png |
| `background` | `transparent`, `opaque`, or `auto` | auto |
| `moderation` | `low` or `auto` | auto |
## Output
Each generated image is uploaded to R2 storage and returned as an asset record with a permanent public URL. The agent receives the URL(s) and may include them in its response.
Before calling the image provider, Fetch Hive checks whether your account has reached its plan storage limit. If the limit is reached, the tool returns an error instead of generating new images.
## Billing
* **OpenAI (`gpt-image-2`)**: token-based billing. Input image tokens, input text tokens, and output tokens are recorded in the completion and appear in your usage dashboard.
* **xAI (Grok Imagine)**: per-image billing at a fixed rate per image generated. Token fields are set to 0.
* **Gemini image models** (`gemini-2.5-flash-image`, `gemini-3.1-flash-lite-image`, `gemini-3.1-flash-image`, `gemini-3-pro-image`): hosted token billing through the Gemini Interactions API in `fetch-image-mcp`. Personal/BYOK Gemini image generation is not supported yet. Input tokens and generated-image output tokens are recorded in the completion for hosted billing.
## Use cases
* Generate product mockups or illustration drafts from a prompt.
* Create supporting visuals during a longer research or writing task.
* Combine with Vector Search and SERP to produce richly illustrated reports.
## Notes
* Image Generation works with all supported LLM providers (OpenAI, Anthropic, xAI, Gemini). Context and credentials travel in a short-lived JWT from Fetch Hive to the image service.
* For personal agents whose LLM provider is not OpenAI or xAI, configure an OpenAI provider key before enabling Image Generation. Gemini personal image generation is not supported yet.
* Agent image generation is executed by Fetch Hive after the model emits `create_image`, so long-running generations are not limited by provider remote MCP timeouts.
* For generating images from a workflow step (not an agent), see the [Image Generation workflow step](../../workflows/steps/ai/image-generation).
* To add or remove tools from an agent, see [Creating and Configuring](../creating-and-configuring).
Generated images appear immediately in chat and become reusable through **Use from this chat**. Reusing an image explicitly selects the existing Asset for that turn; older images are not automatically sent to the model.
# Linear
Source: https://docs.fetchhive.com/agents/mcp-tools/linear
Give an agent access to your connected Linear workspace so it can create and manage issues, search teams, and track project work
Linear gives your agent access to your connected Linear workspace. The agent can create issues, search and list existing issues, update issue status and details, and list teams while it responds to chat messages or completes tasks.
## What it does
When Linear is enabled on an agent, the agent can automatically perform Linear actions as part of its reasoning process. You ask a question or give it a task — the agent decides when and how to use Linear on your behalf.
## Prerequisites
You must have an active Linear connection in your workspace before enabling this tool. If no active connection exists, the toggle is disabled.
1. Go to **Integrations** for your workspace.
2. Find **Linear** in the integrations grid.
3. Click **Connect** and complete the OAuth flow.
4. Return to your agent and enable the tool.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **Linear**. The Linear node appears on the canvas.
4. Click the node to open the **Settings** panel on the right.
5. In the **Authentication** field, select the connected Linear account the agent should use.
6. If no active connection is found, the settings panel shows a warning with a link to **Integrations** to connect first.
## Use cases
* Automatically create a Linear issue when a bug or task is identified in a chat session.
* Look up open issues assigned to a team and summarize them.
* Update the status or priority of an issue based on the result of a workflow.
* List teams so the agent can pick the correct team when creating issues.
## Notes
* The agent uses your connected Linear account to perform actions. Make sure the OAuth connection has sufficient permissions for the teams and projects you want to manage.
* This tool counts as 1 credit per action the agent performs.
See also: [Integrations](../../workspace/integrations), [Creating and Configuring](../creating-and-configuring)
# OpenAI Code Interpreter
Source: https://docs.fetchhive.com/agents/mcp-tools/openai-code-interpreter
Add OpenAI Code Interpreter so an agent can run Python for exact computation and data analysis
OpenAI Code Interpreter gives an OpenAI agent a sandboxed Python environment for exact math, data slicing, and analysis.
## What it does
When enabled, the agent can call OpenAI's hosted **python tool** to write and run Python in an ephemeral container. Use it when you need exact results that language models alone cannot guarantee — for example splitting spreadsheet rows into precise batches, computing statistics, or transforming tabular data.
**Important:** Prefer **File Tools** (`write_file`) for deliverable PDF/DOCX/XLSX/CSV when the model can print text content. If the model still saves files inside the sandbox and cites them, Fetch Hive automatically downloads those container files and stores them as workspace assets (rewriting `sandbox:` links to real download URLs).
## Requirements
* Agent provider must be **OpenAI**.
* The tool is **not** enabled by default — add it from the tool picker.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **OpenAI Code Interpreter**.
There are no per-tool settings in v1. Containers use OpenAI's default **1 GB** memory tier.
## How it works with File Tools
Typical flow for spreadsheet slicing:
1. Document attachments (csv/xlsx/pdf/docx/txt/md) on the turn are **auto-mounted** into the Code Interpreter sandbox at `/mnt/data/` for both hosted and BYOK OpenAI keys (up to 10 files, 50 MB each). The sandbox has **no internet access** — the agent should read mounted files directly, not fetch URLs.
2. Code Interpreter runs Python to slice or transform the data and **prints** CSV/JSON.
3. The agent calls `write_file` with that text to create downloadable XLSX/CSV assets.
If the model instead writes files into `/mnt/data` and links them with `sandbox:` URLs, Fetch Hive captures those container files via OpenAI's Containers API and promotes them to real workspace assets (same storage path as `write_file`). Prefer `write_file` when possible. Mounted input files are re-uploaded to OpenAI each turn (1-hour expiry) and do not persist across turns.
## Limitations (v1)
* **OpenAI only** — Anthropic and xAI code-execution tools are not wired yet.
* **No multi-turn Python state** — each agent turn starts a fresh container; variables from a previous turn do not persist.
* **Fixed 1 GB memory** — higher OpenAI memory tiers are not exposed yet.
* **Attachment mount caps** — at most 10 document attachments / 50 MB each are mounted per turn; larger or excess files are skipped (File Tools `read_file` remains available).
* Each Code Interpreter call counts as **1 task credit** (same pattern as GPT Search). Container-minute spend is tracked only as estimated operator metadata (`estimated: true`) on the completion — not a separate user-facing USD line item. On hosted keys, OpenAI container minutes are absorbed by Fetch Hive. Mounting attachments via the Files API does not add extra task credits.
## Use cases
* Exact row slicing (rows 1–50, 51–100, …) before exporting XLSX batches.
* Numerical / statistical calculations that must be precise.
* Parsing or reshaping tabular data before writing a file.
## Notes
* Use [Testing with Chat](../testing-with-chat) to watch Code Interpreter and File Tools calls during a conversation.
* To add or remove tools from an agent, see [Creating and Configuring](../creating-and-configuring).
* See also [File Tools](./file-tools) for creating downloadable assets.
# Sonar Web Search
Source: https://docs.fetchhive.com/agents/mcp-tools/perplexity-search
Add Sonar Web Search to an agent and control its search context size and location
Sonar Web Search gives your agent built-in web search when using a Perplexity agent model in the Fetch Hive editor.
## What it does
This tool helps a Perplexity-powered agent search the web when you explicitly add **Sonar Web Search** to the agent. Unlike legacy Sonar prompt runs, agents do not search automatically — web search only runs when this tool is enabled.
The separate **Perplexity Search** tool uses the standalone Search API for
cross-provider structured results; this page covers only the native Sonar
agent search path.
## Adding the tool to an agent
1. Open an agent that uses a Perplexity model.
2. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
3. In **MCP Tools**, click **Sonar Web Search**.
After you add the tool, select the **Sonar Web Search** node to open its settings sheet.
## Configuration
Sonar Web Search exposes two configuration fields in the settings sheet.
| Option | Description |
| -------------------- | ------------------------------------------------------------------------------------------------- |
| **Context Size** | Controls how much search context Fetch Hive returns to the agent. The default is **Medium**. |
| **Location Country** | Targets the search to a supported country in the settings list. The default is **United States**. |
Hive Agent runs can override **Location Country** from **Start Run** → **Search country** for that execution.
1. Select the **Sonar Web Search** node in the editor.
2. Set **Context Size** to **Low**, **Medium**, or **High**.
3. Set **Location Country** to the country you want to target.
## Billing
Sonar Web Search is billed as a hosted LLM tool completion (similar to Anthropic Web Search), not against the provider-tool daily cap used by SERP API or Google Search.
## Related
* [Overview](./overview) — model compatibility matrix
* [GPT Search](./gpt-search) — OpenAI-native web search tool
* [Perplexity Search](./perplexity-search-api) — standalone Search API tool available across model providers
# Perplexity Search
Source: https://docs.fetchhive.com/agents/mcp-tools/perplexity-search-api
Give a Hive Agent cross-provider access to Perplexity's standalone Search API
**Perplexity Search** lets a Hive Agent call Perplexity's standalone Search API regardless of whether the agent model is OpenAI, Anthropic, xAI, Gemini, or Perplexity.
The model sees a function named `search_perplexity` and supplies only a required query. All search options are saved on the tool and cannot be overridden by the model.
## Configuration
1. Add **Perplexity Search** from the agent tool selector.
2. Set **Maximum results** from 1 to 20. The default is 10.
3. Choose a country, or **No country restriction**.
4. Choose **Search context size** (`Low`, `Medium`, or `High`), or select **Custom token limits** and set the optional total and per-page token limits. Perplexity does not accept a context preset together with token limits.
5. Optionally select up to 20 search languages.
6. Optionally set updated-after, updated-before, published-after, and published-before dates.
7. Optionally restrict publication recency to the past hour, day, week, month, or year.
8. Choose the agent's credential mode. Hosted mode uses Fetch Hive's key; personal mode requires the workspace's enabled Perplexity integration.
Hive Agent runs can override the saved country from **Start Run** → **Search country** for that execution.
Token limits accept values from 1 to 1,000,000. Date fields are sent to Perplexity in `MM/DD/YYYY` format. For each date window, the **after** date must be earlier than the **before** date.
The tool can be selected at the same time as **Sonar Web Search**. They remain separate tools.
## Result and billing behavior
Each model invocation returns the query and a normalized `results` array. Completed calls render with the standard search-result cards.
Every actual invocation consumes one provider-tool limit unit. If the model never calls the function, no unit is consumed. Successful hosted calls use the fixed Search API cost; successful personal calls use one platform task. Failed calls are not billed.
## Perplexity Search versus Sonar Web Search
* **Perplexity Search** is a standalone API function available across model providers.
* **Sonar Web Search** is native search for Perplexity Sonar agent models.
See also: [Sonar Web Search](./perplexity-search), [Agent tools overview](./overview), and [Agent logs](../../agents/logs)
# Pinecone
Source: https://docs.fetchhive.com/agents/mcp-tools/pinecone
Let an agent search and write one configured Pinecone namespace
Add **Pinecone** to an agent, then select a compatible index, namespace, and result limit (1–20, default 10).
The model receives two bounded functions: `pinecone_search(query, top_k?)` and `pinecone_write(content, record_id?, metadata?)`. Fetch Hive injects the saved index and namespace server-side, so the model cannot access another index or namespace. The tool cannot delete records or manage indexes.
Writes create one raw-text record per call. A blank record ID generates a UUID; an existing ID replaces that complete record. Metadata must be flat and may contain strings, finite numbers, booleans, or arrays of strings. Pinecone is eventually consistent, so a successful write may not appear in search immediately.
# X Search
Source: https://docs.fetchhive.com/agents/mcp-tools/x-search
Search X/Twitter posts and content through Grok's native x_search tool
X Search lets a Grok-powered agent search posts and content on X, formerly Twitter, while it responds.
## What it does
This tool uses xAI's native `x_search` capability. It can help an agent find recent posts, discussions, and threads on X without connecting a separate MCP server.
## Requirements
X Search is only available when your agent is configured to use an **xAI (Grok)** model. When your agent uses a different model provider, use [GPT Search](./gpt-search), [Google Search](./google-search), or [xAI Web Search](./xai-search) where appropriate.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Make sure the agent's model is set to an xAI Grok model.
3. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
4. In **MCP Tools**, click **X Search**.
## Configuration
X Search settings are configured in the MCP tool settings sheet:
| Parameter | Description |
| ---------------------------- | ---------------------------------------------------------------------------------- |
| `allowed_x_handles` | Only consider posts from specific X handles (max 20). The default is blank. |
| `excluded_x_handles` | Exclude posts from specific X handles (max 20). The default is blank. |
| `included_domains` | Prefer or limit linked content to specific domains (max 20). The default is blank. |
| `excluded_domains` | Exclude linked content from specific domains (max 20). The default is blank. |
| `from_date` | Start date for search range (`YYYY-MM-DD`). The default is blank. |
| `to_date` | End date for search range (`YYYY-MM-DD`). The default is blank. |
| `enable_image_understanding` | Enable analysis of images in posts. The default is disabled. |
| `enable_video_understanding` | Enable analysis of videos in posts. The default is disabled. |
Notes:
* `Allowed X Handles` and `Excluded X Handles` are mutually exclusive.
* Dates must be valid ISO date strings (`YYYY-MM-DD`).
## Use cases
* Monitor what people are saying about a company, product, topic, or event on X.
* Find recent posts and threads before answering a time-sensitive question.
* Gather social context and public reactions from X content.
## Billing
X Search is billed at **\$0.005 per completed request/tool call**.
## Notes
* X Search searches X/Twitter posts and content. For public web results from Grok, use [xAI Web Search](./xai-search).
* This tool is powered by xAI's native `x_search` capability, not an external MCP server.
* Use **Chat** in the editor to see when the agent calls **X Search** during a test run. See [Testing with Chat](../testing-with-chat).
# xAI Web Search
Source: https://docs.fetchhive.com/agents/mcp-tools/xai-search
Let a Grok-powered agent search the public web using xAI's native web search tool
xAI Web Search gives your agent access to live public web search when it is powered by an xAI Grok model.
## What it does
This tool lets a Grok agent look up current information on the web while it responds. It uses xAI's native `web_search` tool, which is built into the Grok model family — no separate MCP server is required.
## Requirements
xAI Web Search is only available when your agent is configured to use an **xAI (Grok)** model. When your agent uses a different model provider (OpenAI, Anthropic, Google, etc.) use [GPT Search](./gpt-search) or [Google Search](./google-search) instead.
## Adding the tool to an agent
1. Open an agent in the editor.
2. Make sure the agent's model is set to an xAI Grok model.
3. Click the button with the tooltip **Add MCP Tool or Sub Agent**.
4. In **MCP Tools**, click **xAI Web Search**.
## Configuration
xAI Web Search does not have any configuration fields in the settings sheet. The search is handled natively by the Grok model.
## Use cases
* Look up current events or recent news using a Grok agent.
* Check live web sources before the agent answers a question.
* Enrich agent responses with up-to-date information from the public web.
## Notes
* This tool is powered by xAI's native `web_search` capability, not an external MCP server. It is automatically available when an xAI model is selected.
* Use **Chat** in the editor to see when the agent calls **xAI Web Search** during a test run. See [Testing with Chat](../testing-with-chat).
* To add or remove tools from an agent, see [Creating and Configuring](../creating-and-configuring).
# Create an agent
Source: https://docs.fetchhive.com/api-reference/agents/create-an-agent
/openapi.yaml post /v1/public/workspaces/{workspace_id}/agents
Creates a new agent in the requested workspace.
# Delete an agent
Source: https://docs.fetchhive.com/api-reference/agents/delete-an-agent
/openapi.yaml delete /v1/public/workspaces/{workspace_id}/agents/{id}
Destroys the agent record.
# Get an agent
Source: https://docs.fetchhive.com/api-reference/agents/get-an-agent
/openapi.yaml get /v1/public/workspaces/{workspace_id}/agents/{id}
Returns a single active agent belonging to the requested workspace.
# Invoke
Source: https://docs.fetchhive.com/api-reference/agents/invoke
Send a message to an agent with the public Fetch Hive API using an agent ID and message
`POST /v1/agent/invoke`
Send a message to an agent from your own app or service.
## Authentication
Send your workspace API key in the `Authorization` header.
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
Agent webhook triggers use the agent webhook secret instead of an API key. See [Webhook trigger](#webhook-trigger).
## Request body
Open an agent in the editor and click **Code Snippet** to see the current public request shape in Fetch Hive.
## Webhook trigger
`POST /v1/agent/webhooks/{agent_id}`
Use an agent webhook trigger when an external service should start an agent run without a workspace API key. The request must include the agent webhook secret in `X-Fetch-Hive-Webhook-Secret`. If a third-party tool cannot set custom headers, use `?secret=YOUR_WEBHOOK_SECRET` as a fallback.
Agent webhook triggers always use callback delivery. Include `async.callback_url`; Fetch Hive returns `202` with `request_id` and `run_status: "running"`, then delivers either `agent.completed` or `agent.failed` to the callback URL.
```bash theme={null}
curl 'https://api.fetchhive.com/v1/agent/webhooks/YOUR_AGENT_ID' \
-H 'X-Fetch-Hive-Webhook-Secret: YOUR_WEBHOOK_SECRET' \
-H 'Content-Type: application/json' \
--data-raw '{
"message": "Summarize the latest ticket",
"thread_id": "external-thread-123",
"metadata": {
"customer_id": "cus_123",
"plan": "enterprise"
},
"user": "external-user-1",
"async": {
"callback_url": "https://example.com/callback"
}
}'
```
`message` is required. `thread_id` is optional and can be reused to resume a caller-managed thread. `metadata` follows the same flat scalar-only rule as normal agent invokes and appears in log filtering.
Fetch Hive signs the outbound callback with the same webhook secret used for inbound trigger authentication.
Callback `data` contains `response` on `agent.completed` and `error` on `agent.failed`; use the top-level `event_type` and `request_id` for terminal state and correlation.
| Field | Type | Required | Description |
| ------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent` | string | Yes | The agent ID |
| `message` | string | Yes | The message you want to send |
| `streaming` | boolean | No | Stream response events instead of waiting for one final JSON response |
| `thread_id` | string | No | An arbitrary string identifying the conversation thread. Fetch Hive creates a new thread on first use and resumes it on subsequent calls with the same value. Ideal for persistent, multi-turn conversations. |
| `messages` | array | No | Previous conversation turns to use as context without persisting history to the database. Each item: `{ "content": string, "role": "user" \| "assistant" \| "system", "attachments"?: array }`. Use this when you manage conversation state yourself. |
| `attachments` | array | No | HTTPS file URLs attached to the current `message`. Each item can be a URL string or an object with `file_url`. Supported document files are CSV, XLSX, PDF, DOCX, and text/Markdown by extension. Images can also be passed here. |
| `metadata` | object | No | Flat caller-defined metadata for audit and log filtering. This is not added to the agent prompt. |
`metadata` must be a flat object. Keys must be non-empty strings, and values must be strings, numbers, booleans, or `null`. Arrays and nested objects are rejected before the run starts.
`attachments` items can be simple URL strings:
```json theme={null}
[
"https://example.com/customer-brief.pdf",
"https://example.com/customer-brief.pdf"
]
```
They can also use this object shape when you want to provide metadata:
```json theme={null}
{
"file_url": "https://example.com/customer-brief.pdf",
"file_name": "customer-brief.pdf",
"file_type": "application/pdf"
}
```
Only `https://` URLs are accepted. Up to five attachments are allowed per
message. Document attachments are
exposed to the agent through the system `read_file` tool as an
`` manifest; the agent calls `read_file` before relying on
document contents. Image attachments are sent to the model as multimodal input.
For image URLs without a file extension, use the object shape with `file_type`
set to an image MIME type (for example `image/png`). If an attachment URL or type is invalid, Fetch Hive returns
`422 Unprocessable Entity` instead of opening the stream.
Supported document attachments:
* CSV: `text/csv`, `.csv`
* XLSX: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `.xlsx`
* PDF: `application/pdf`, `.pdf`
* DOCX: `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `.docx`
* Text and Markdown by extension: `.txt`, `.md`, `.markdown`
For extensionless URLs, such as Fetch Hive Media Library URLs, pass the URL
directly. Fetch Hive allow-lists the URL for `read_file`, and the file tool
detects the actual type when it fetches the file.
Valid:
```json theme={null}
{
"metadata": {
"customer_id": "cus_123",
"plan": "enterprise",
"trial": false,
"invoice_count": 12,
"region": null
}
}
```
Invalid:
```json theme={null}
{
"metadata": {
"customer": {
"id": "cus_123"
},
"tags": ["enterprise"]
}
}
```
The code snippet dialog uses this body shape:
```json theme={null}
{
"agent": "AGENT_UUID",
"message": "Your message here",
"streaming": true,
"attachments": [
"https://example.com/customer-brief.pdf"
],
"metadata": {
"customer_id": "cus_123",
"plan": "enterprise"
}
}
```
When using `thread_id` for persistent conversations:
```json theme={null}
{
"agent": "AGENT_UUID",
"message": "What did we discuss last time?",
"streaming": true,
"thread_id": "user-456-support-session"
}
```
When using `messages` for caller-managed (stateless) history:
```json theme={null}
{
"agent": "AGENT_UUID",
"message": "What else should I know?",
"streaming": true,
"messages": [
{
"content": "What are the latest AI trends?",
"role": "user",
"attachments": [
"https://example.com/market-data.csv"
]
},
{ "content": "Teams are focusing on evals, routing, and observability.", "role": "assistant" }
]
}
```
If a previous assistant turn generated a file, pass that file back on the
relevant history message through `messages[].attachments`. Fetch Hive uses the
structured attachment URLs in current and historical messages to authorize
`read_file` access for follow-up turns; URLs mentioned only in plain text are
not treated as file-tool attachments.
## Response
If `streaming` is `true`, Fetch Hive returns a stream of events. If the provider fails after the stream has opened, Fetch Hive sends a final `error` event before closing the stream. If the client disconnects first, Fetch Hive treats it as a silent cancellation and does not create a failed agent run, bill usage, or report a provider-error event unless the provider had already completed and usage was committed.
Example reasoning event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "reasoning",
"response": "Looking at the latest model releases..."
}
```
Example response event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "response",
"response": "Teams are standardizing around evals, routing, and observability.",
"done": false
}
```
Example tool event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "tool",
"tool_id": "tool_123",
"tool": "google_search",
"tool_input": {
"query": "latest AI infrastructure trends 2026"
},
"observation": {
"results": []
}
}
```
Example final usage event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "usage",
"usage": {
"duration": 4.79230260848999,
"input_tokens": {
"total_tokens": 24,
"cached_tokens": 0,
"cached_read_tokens": 0,
"cache_write_tokens": 0
},
"output_tokens": {
"total_tokens": 170,
"reasoning_tokens": 64
},
"total_tokens": 194
},
"stop_reason": "completed"
}
```
Example error event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "error",
"id": "msg_019d52846ea37682b03522fd0695cc43",
"error": "openai provider stream error: HTTP 400: invalid request",
"message": "openai provider stream error: HTTP 400: invalid request",
"provider": "openai",
"error_type": "provider_stream_error",
"status_code": 502
}
```
If `streaming` is `false`, Fetch Hive returns one JSON response. Provider execution failures return `502 Bad Gateway` with an `error` message.
```json theme={null}
{
"request_id": "req_019d528660dd7e22b15e5b13a1931c50",
"model": "gpt-5-nano-2025-08-07",
"duration": 4.641960144042969,
"response": "Teams are moving from simple wrappers to systems with evals, tool routing, and tighter cost controls.",
"reasoning": "The request asks for a short summary of current infrastructure trends.",
"usage": {
"input_tokens": {
"total_tokens": 24,
"cached_tokens": 0,
"cached_read_tokens": 0,
"cache_write_tokens": 0
},
"output_tokens": {
"total_tokens": 187,
"reasoning_tokens": 64
},
"total_tokens": 211
},
"stop_reason": "completed"
}
```
## Example
```bash theme={null}
curl 'https://api.fetchhive.com/v1/agent/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
"agent": "AGENT_UUID",
"message": "Summarize the latest AI infrastructure trends",
"metadata": {
"customer_id": "cus_123",
"plan": "enterprise"
},
"streaming": true
}' \
--compressed
```
## Related
* See [Authentication](./authentication) for API key setup
* See [Agents](../agents/overview) for agent setup and runtime context
* See [Testing with Chat](../agents/testing-with-chat) for the in-editor testing flow
* See [Run with API](../agents/run-with-api) for an agent-focused guide
# List public workspace agents
Source: https://docs.fetchhive.com/api-reference/agents/list-public-workspace-agents
/openapi.yaml get /v1/public/workspaces/{workspace_id}/agents
Returns standalone agents scoped to the requested public API workspace.
# Update an agent
Source: https://docs.fetchhive.com/api-reference/agents/update-an-agent
/openapi.yaml patch /v1/public/workspaces/{workspace_id}/agents/{id}
Updates an existing agent in the requested workspace.
# List public workspace assets
Source: https://docs.fetchhive.com/api-reference/assets/list-public-workspace-assets
/openapi.yaml get /v1/public/workspaces/{workspace_id}/assets
Returns assets scoped to the workspace attached to the public API key.
# Upload a public workspace asset
Source: https://docs.fetchhive.com/api-reference/assets/upload-a-public-workspace-asset
/openapi.yaml post /v1/public/workspaces/{workspace_id}/assets
Uploads a file and creates a workspace-scoped Asset that can be used as a Hive Agent source.
# Authentication
Source: https://docs.fetchhive.com/api-reference/authentication
Authenticate Fetch Hive API requests with a workspace API key from the dashboard
Use a workspace API key to authenticate requests to the public Fetch Hive API.
## Authentication header
Send your API key in the `Authorization` header on every request:
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
Fetch Hive uses the same bearer header for public invoke endpoints and public resource endpoints.
## How do I create an API key?
Open **Settings**, then click **API Keys**.
If your workspace does not have a default key yet, click **Create Default Key**.
If you want another key for a specific service or environment, click **Add API Key**.
Choose the environment you want to use:
* **Production**
* **Staging**
* **Development**
Copy the full key when Fetch Hive shows **Your New API Key**. After that dialog closes, Fetch Hive usually only shows the key prefix.
## Example request
```bash theme={null}
curl 'https://api.fetchhive.com/v1/prompt/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
"deployment": "YOUR_DEPLOYMENT_NAME",
"variant": "YOUR_VARIANT_NAME",
"inputs": {
"text": "Fetch Hive helps teams ship AI products faster."
},
"streaming": true
}' \
--compressed
```
## What happens when authentication fails?
If the API key is missing, invalid, or revoked, Fetch Hive returns an error response.
```json theme={null}
{
"error": "Invalid access."
}
```
See [Errors and rate limits](./errors-and-rate-limits) for common status codes and error shapes. For API key management in the dashboard, see [API keys](../workspace/api-keys).
# Error codes
Source: https://docs.fetchhive.com/api-reference/error-codes
Stable Fetch Hive API error codes, response fields, and client handling guidance
Fetch Hive API errors include a human-readable `message`, a stable `error_code`, and `error` as a compatibility alias for the same message. Older plan and rate-limit responses may also include `code`; treat `code` as a deprecated alias and read `error_code` first.
Fetch Hive returns localized error messages based on your account language setting. Error codes are stable identifiers you can rely on in client code.
## Catalog endpoint
Use `GET /v1/error_codes` to retrieve the public catalog. The endpoint is unauthenticated because it returns static API contract metadata. Pass `?locale=es` to request Spanish catalog copy; unsupported or unavailable locales fall back to English.
```json theme={null}
{
"locale": "en",
"default_field": "error_code",
"compatibility_aliases": ["code"],
"codes": [
{
"code": "model_deprecated",
"status": 422,
"field": "error_code",
"message_key": "errors.codes.model_deprecated",
"message": "The selected model \"%{model}\" is no longer available. Choose a current model and try again.",
"field_aliases": [],
"category": "runtime",
"client_action_key": "errors.client_actions.model_deprecated",
"client_action": "Choose an active model and retry."
}
]
}
```
## JSON error shape
```json theme={null}
{
"error": "The selected model \"old-model\" is no longer available. Choose a current model and try again.",
"message": "The selected model \"old-model\" is no longer available. Choose a current model and try again.",
"error_code": "model_deprecated"
}
```
## SSE error shape
Streaming endpoints send errors as Server-Sent Events with `type: "error"`.
```json theme={null}
{
"type": "error",
"error": "Provider request failed",
"message": "Provider request failed",
"error_code": "provider_error",
"error_type": "provider_error",
"status_code": 502
}
```
## Codes
| Code | Field | Status | Meaning | Client action |
| --------------------------------------- | ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `model_deprecated` | `error_code` | `422` | The saved prompt, agent, workflow step, deployment, or fallback model is no longer available. | Choose an active model and retry. |
| `personal_model_missing_credentials` | `error_code` | `422` | A personal-model run needs provider credentials that are not connected. | Connect credentials or switch to a hosted/current model. |
| `personal_model_invalid_credentials` | `error_code` | `422` | Provider credentials were present but rejected by the provider. | Reconnect or rotate the provider credential. |
| `personal_charge_type_not_allowed` | `error_code` | `402` | Personal charge type requires a paid plan (Growth or above). | Upgrade to use your own API keys, or switch to Hosted. |
| `insufficient_hosted_llm_credits` | `error_code` | `402` | The workspace does not have enough hosted LLM credits for the run. | Add credits or upgrade. On a paid plan you can also switch to a personal provider key. |
| `account_credit_cap_reached` | `error_code` | `422` | The account has reached its general credit cap. | Upgrade or wait for more credits before retrying. |
| `asset_storage_limit_reached` | `error_code` | `402` | The workspace has reached its asset storage limit. | Delete assets or upgrade the workspace plan. |
| `vision_not_supported` | `error_code` | `422` | The selected model cannot process image inputs. | Select a vision-capable model or remove image inputs. |
| `workflow_step_limit_reached` | `error_code` | `402` | The workflow has reached the plan's step limit. | Remove steps or upgrade. |
| `workspace_limit_reached` | `error_code` | `402` | The account has reached the plan's workspace limit. | Delete a workspace or upgrade. |
| `api_rate_limit_exceeded` | `error_code` | `429` | The API key has reached its daily request cap. | Retry after reset or upgrade. |
| `guest_limit_exceeded` | `error_code` | `429` | Guest chat hit an IP, session, fingerprint, or thread usage cap. | Sign up or log in to continue. |
| `guest_signup_required` | `error_code` | `403` | Guest chat cannot use a gated feature (e.g. uploads). | Sign up or log in to continue. |
| `guest_session_required` | `error_code` | `403` | Guest session cookie missing or expired. | Refresh; SPA remints automatically. |
| `guest_unavailable` | `error_code` | `503` | Guest chat is temporarily disabled (kill switch / high volume). | Sign up or log in to continue. |
| `provider_tool_rate_limit_exceeded` | `error_code` | `429` | The account has reached its daily provider tool call cap. | Retry after reset or upgrade. |
| `log_range_limit_exceeded` | `error_code` | `402` | The requested log range is larger than the allowed window. | Narrow the date range. |
| `experiment_run_result_limit_exceeded` | `error_code` | `422` | An experiment run would create more result cells than the current plan allows. | Reduce dataset rows or active candidates, or upgrade. |
| `experiment_candidate_type_unsupported` | `error_code` | `422` | The experiment candidate type is not supported by prompt-only experiments. | Use a dashboard prompt or deployed prompt candidate. |
| `experiment_run_unsupported_candidates` | `error_code` | `422` | An experiment run includes active candidates that are not runnable in prompt-only experiments. | Archive unsupported candidates and retry. |
| `experiment_dataset_row_limit_exceeded` | `error_code` | `422` | A dataset version would exceed the 10,000 row limit. | Reduce the CSV rows and retry. |
| `experiment_run_start_failed` | `error_code` | `503` | Fetch Hive could not start the experiment workflow after creating the run record. | Retry the run; contact support if it persists. |
| `iteration_limit_exceeded` | `error_code` | `422` | A workflow iteration exceeded the allowed loop count. | Reduce input size or iteration count. |
| `internal_server_error` | `error_code` | `500` | Fetch Hive hit an unexpected internal error. | Retry later; contact support if it persists. |
| `too_many_requests` | `error_code` | `429` | A provider or Fetch Hive rejected the request because of rate limiting. | Back off and retry. |
| `concurrency_limit_reached` | `error_code` | `429` | The account has reached its active workflow concurrency limit. | Retry later or use callback delivery. |
| `validation_error` | `error_code` | `400`/`422` | The request parameters were invalid before the run started. | Fix the request body or query parameters. |
| `unsupported_provider` | `error_code` | `400` | The configured provider is not supported by that runtime path. | Select a supported provider/model. |
| `database_error` | `error_code` | `500` | Fetch Hive could not complete the requested operation. | Retry later; contact support if it persists. |
| `config_error` | `error_code` | `500` | Runtime configuration was missing or invalid. | Contact support. |
| `provider_error` | `error_code` | `502` | A model provider rejected or failed the request. | Check provider status/input and retry. |
| `agent_completion_persistence_failed` | `error_code` | `503` | Fetch Hive could not persist an agent completion after provider execution. | Retry the request; contact support if it persists. |
| `upstream_request_failed` | `error_code` | `502`/`504` | Fetch Hive could not get a successful response from an upstream service. | Retry later; contact support if it persists. |
| `workflow_enqueue_failed` | `error_code` | `500` | A workflow run could not be enqueued. | Retry the workflow run. |
| `not_found` | `error_code` | `404` | The requested resource was not found for the authenticated account. | Check the identifier and account context. |
| `resource_not_found` | `error_code` | `404` | The requested resource was not found. | Check the identifier and account context. |
| `invalid_access` | `error_code` | `401` | The dashboard or public request is not authenticated for the requested account. | Sign in again and retry. |
| `unauthorized` | `error_code` | `401` | The request is missing valid authorization. | Sign in again and retry. |
| `forbidden` | `error_code` | `403` | The caller is authenticated but not allowed to perform the action. | Use an account with access or contact an administrator. |
| `invalid_api_key` | `error_code` | `401` | A global or API-key authenticated request used an invalid key. | Check the API key and retry. |
| `invalid_request` | `error_code` | `400` | A request field is invalid. | Fix the request and retry. |
| `missing_required_field` | `error_code` | `422` | A required request field is missing. | Provide the required field and retry. |
| `missing_required_header` | `error_code` | `400` | A required request header is missing. | Send the required header and retry. |
| `validation_failed` | `error_code` | `422` | Request validation failed; details are returned in `errors` or `details`. | Fix the highlighted fields and retry. |
| `payment_failed` | `error_code` | `422` | A Stripe payment flow failed. | Check the payment method and retry. |
| `credit_pack_pricing_changed` | `error_code` | `409` | The Hosted LLM credit-pack quote is missing or no longer current. | Review the returned purchase summary and confirm the updated total. |
| `invalid_hosted_llm_credit_amount` | `error_code` | `422` | The custom Hosted LLM wallet credit amount is missing, malformed, below $10, above $999,999, or not a whole-dollar value. | Enter a whole-dollar amount between $10 and $999,999 and retry. |
| `billing_configuration_missing` | `error_code` | `422` | A requested plan or billing path is missing server-side Stripe configuration. | Contact support. |
| `stripe_customer_creation_failed` | `error_code` | `422` | Fetch Hive could not create or load the Stripe customer for the account. | Retry later; contact support if it persists. |
| `promotion_code_invalid` | `error_code` | `200` | A discount code is missing, invalid, expired, or rejected by Stripe. | Check the discount code and retry. |
| `archive_restore_conflict` | `error_code` | `409` | An archive restore is already running for the account. | Wait for the existing restore to finish before retrying. |
| `record_locked` | `error_code` | `409` | The resource could not be updated because another update was in progress. | Retry the request. |
| `completion_resolution_failed` | `error_code` | `500` | Fetch Hive could not resolve a completion back to its dashboard URL. | Retry later; contact support if it persists. |
| `integration_connection_failed` | `error_code` | `502` | An integration connection could not be initiated or synced. | Reconnect the integration and retry. |
| `webhook_signature_invalid` | `error_code` | `400` | A webhook signature could not be verified. | Verify the webhook signing secret and retry. |
| `webhook_signature_not_configured` | `error_code` | `500` | A webhook signing secret is missing on the server. | Configure the webhook signing secret before retrying. |
| `webhook_payload_invalid` | `error_code` | `400` | A webhook payload could not be parsed. | Send a valid webhook payload. |
| `mcp_connection_failed` | `error_code` | `422` | A workspace MCP server test failed. | Check the MCP server URL, auth, and response format. |
| `unsupported_resource_type` | `error_code` | `400` | The requested resource type is not supported. | Use a supported resource type. |
For `workflow_step_limit_reached`, `workspace_limit_reached`, `api_rate_limit_exceeded`, and `log_range_limit_exceeded`, responses may also include `code` with the same value for older clients.
# Errors and rate limits
Source: https://docs.fetchhive.com/api-reference/errors-and-rate-limits
Common Fetch Hive API error responses, status codes, and workflow concurrency behavior
Fetch Hive returns JSON errors for invalid or failed public API requests. Runtime public API errors include a human-readable `message`, a stable code, and `error` as a compatibility alias.
## Error response format
```json theme={null}
{
"error": "Invalid access.",
"message": "Invalid access.",
"error_code": "validation_error"
}
```
Some plan and rate-limit responses also include `code` for compatibility with existing clients. New clients should read `error_code`. See [Error Codes](./error-codes) for the complete code list, catalog endpoint, and client handling guidance.
## Common status codes
### `401 Unauthorized`
Fetch Hive returns `401` when the `Authorization` header is missing, invalid, or uses a revoked API key.
Example:
```json theme={null}
{
"error": "Invalid access."
}
```
### `404 Not Found`
Fetch Hive returns `404` when the resource does not exist for your account.
Example workflow run response:
```json theme={null}
{
"error": "Prompt workflow run not found"
}
```
Example request lookup response:
```json theme={null}
{
"error": "Request not found"
}
```
### `422 Unprocessable Entity`
Fetch Hive returns `422` when the request is authenticated but invalid for that endpoint.
Examples:
```json theme={null}
{
"error": "Agent not found."
}
```
```json theme={null}
{
"error": "Data set not found."
}
```
```json theme={null}
{
"error": "You've reached your credit cap."
}
```
### `502 Bad Gateway`
Fetch Hive returns `502` when a provider fails while processing a prompt or agent request.
Example:
```json theme={null}
{
"error": "openai API error: provider rejected the request"
}
```
## Rate limits and concurrency
Fetch Hive tracks **two independent daily meters** (UTC midnight reset):
1. **Public API** — counts requests authenticated with an API key through public/stream endpoints (including the Rust public invoke auth hop to `validate_key`). Cap comes from `plan.rate_limit_per_day`. Dashboard and other `/v1/private/*` first-party routes authenticate the same way but **do not** count against this meter.
2. **Provider tools** — counts costly third-party workflow tool runs (Google/Bing/Exa search, website scrape, etc.) from the dashboard, schedules, and public workflow API. Cap comes from `plan.provider_tool_calls_per_day`. Growth, Pro, and Enterprise have no provider-tool cap (`nil`).
Workflow failures from provider-tool caps return a plain error string in the run payload (same style as credit-cap errors). The structured code `provider_tool_rate_limit_exceeded` is returned by the internal agent pre-flight endpoint.
### Public API daily cap
Public API requests count against your plan daily API call cap. If you exceed that cap, Fetch Hive returns `429 Too Many Requests` before running the request.
Example daily API cap response:
```json theme={null}
{
"error": "Daily API rate limit reached",
"code": "api_rate_limit_exceeded",
"message": "You have reached your daily limit of 50 API calls. Resets at midnight UTC. Upgrade your plan for higher limits.",
"limit": 50,
"current": 50
}
```
### Provider tool daily cap
| Plan | Provider tool calls / day |
| ------------------------- | ------------------------- |
| Developer | 15 |
| Lifetime | 50 |
| Growth / Pro / Enterprise | Unlimited |
Example workflow failure message:
```json theme={null}
{
"error": "You've reached your daily limit of 15 provider tool calls. Resets at midnight UTC."
}
```
### Workflow concurrency
Workflow concurrency depends on your plan.
| Plan | Concurrency cap |
| ---------- | --------------- |
| Lite | 1 |
| Starter | 3 |
| Pro | 5 |
| Entreprise | Custom |
If you exceed your concurrency cap, Fetch Hive returns `429 Too Many Requests`.
Example:
```json theme={null}
{
"error": "You've reached your concurrency limit. Try again later or use async mode."
}
```
If you see this response on a workflow request, retry later or switch to callback delivery so Fetch Hive can queue the run.
## Related
* See [Authentication](./authentication) for the required bearer header
* See [Error Codes](./error-codes) for stable `error_code` values and `GET /v1/error_codes`
* See [Invoke Workflow](./workflows/invoke) for callback-delivery workflow requests
# Invoke
Source: https://docs.fetchhive.com/api-reference/hive-agents/invoke
Start Hive Agent runs from the public API with callback delivery
Use the public API when your app needs to start a Hive Agent run outside the dashboard. The API starts the run asynchronously, returns identifiers immediately, and sends a signed callback when the run finishes.
Hive Agent invocation does not stream and does not wait for the final answer in the HTTP response. Open [Logs](./logs) to inspect status, trace, costs, node output, partial results, callback attempts, and the final response.
## Endpoint
```http theme={null}
POST /v1/stream/hive_agent/invoke
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```
## Request body
```json theme={null}
{
"hive_agent": "agent_task_uuid",
"objective": "Research competitors and summarize verified findings",
"search_location_country": "US",
"sources": {
"website_urls": [],
"asset_ids": [],
"knowledge_base_ids": [],
"knowledge_base_item_ids": []
},
"metadata": {},
"async": {
"enabled": true,
"callback_url": "https://example.com/hive-agent-callback"
}
}
```
`hive_agent` is the Hive Agent ID from the dashboard. The API key must belong to the same workspace as the Hive Agent. Only customer-created Hive Agents in your workspace can be invoked through this endpoint.
`objective` should be specific enough for the planner to create useful work nodes.
`search_location_country` is optional and defaults to `US`. Pass an ISO 3166-1 alpha-2 country code to localize web search tools for this run. It overrides Location Country on GPT Search, Anthropic Web Search, Sonar Web Search, and Perplexity Search for this execution only.
`sources` is optional but recommended when the run needs grounded context. Pass website URLs, asset IDs, knowledge base IDs, or knowledge base item IDs that already exist in the workspace.
Use `GET /v1/public/workspaces/{workspace_id}/knowledge_bases` to list knowledge bases, `GET /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}/items` to list items, and `GET /v1/public/workspaces/{workspace_id}/assets` to list assets. Upload a file with `POST /v1/public/workspaces/{workspace_id}/assets` before passing its `asset.id` in `sources.asset_ids`.
`metadata` is optional caller metadata for your own correlation, such as a customer ID or job ID.
`async.callback_url` is required. Fetch Hive sends the terminal callback to this HTTPS URL after the run completes, fails, or is cancelled. `async.enabled` must be `true`.
## Response
Fetch Hive returns `202 Accepted` when the run is queued for execution.
```json theme={null}
{
"run_id": "agent_task_run_uuid",
"request_id": "req_018c9f8ea1b2c3d4e5f6g7h8i9j0k1l2",
"status": "pending",
"webhook_secret": "whsec_..."
}
```
Save `request_id` if you need to find the run later in logs. Store `webhook_secret` so your callback receiver can verify `X-Fetch-Hive-Signature`. The initial status is usually `pending`; the runtime updates status as source preparation, planning, execution, verification, and composition continue.
## cURL example
```bash theme={null}
curl https://api.fetchhive.com/v1/stream/hive_agent/invoke \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"hive_agent": "agent_task_uuid",
"objective": "Research competitors and summarize verified findings",
"sources": {
"website_urls": ["https://example.com"],
"asset_ids": [],
"knowledge_base_ids": [],
"knowledge_base_item_ids": []
},
"metadata": {
"customer_id": "cus_123"
},
"async": {
"enabled": true,
"callback_url": "https://example.com/hive-agent-callback"
}
}'
```
## Callback payload
Fetch Hive sends a signed JSON payload to `async.callback_url` when the run reaches a terminal status. The `event_type` is one of `hive_agent.completed`, `hive_agent.failed`, or `hive_agent.cancelled`.
```json theme={null}
{
"event_type": "hive_agent.completed",
"request_id": "req_018c9f8ea1b2c3d4e5f6g7h8i9j0k1l2",
"data": {
"run_id": "agent_task_run_uuid",
"hive_agent_id": "agent_task_uuid",
"hive_agent_name": "Competitor Research",
"status": "completed",
"success": true,
"objective": "Research competitors and summarize verified findings",
"final_response": {},
"error_message": null,
"metadata": {
"customer_id": "cus_123"
},
"sources": []
}
}
```
Callbacks use the same signature headers as other Fetch Hive outbound webhooks: `X-Fetch-Hive-Signature`, `X-Fetch-Hive-Timestamp`, and `X-Fetch-Hive-Webhook-Id`. See [Callback Delivery and Webhook Triggers](../workflows/async-and-webhooks) for verification guidance.
## Find results
Open **Hive Agents** > **Logs** and search by Hive Agent name, objective, status, or request ID. Open the run to review node work, verifier feedback, source handling, budget events, trace spans, and the final response.
The run detail also shows callback delivery attempts and retry state. There is no synchronous wait or streaming option for Hive Agent public invocation in this version.
# List public workspace knowledge base items
Source: https://docs.fetchhive.com/api-reference/knowledge-base-items/list-public-workspace-knowledge-base-items
/openapi.yaml get /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}/items
Returns items for a knowledge base in the requested public API workspace.
# Create a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/create-a-knowledge-base
/openapi.yaml post /v1/public/workspaces/{workspace_id}/knowledge_bases
Creates a new knowledge base in the requested workspace.
# Delete a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/delete-a-knowledge-base
/openapi.yaml delete /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}
Marks a knowledge base for deletion. Cleanup continues asynchronously in the background.
# Get a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/get-a-knowledge-base
/openapi.yaml get /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}
Returns a single active knowledge base belonging to the requested workspace.
# List public workspace knowledge bases
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/list-public-workspace-knowledge-bases
/openapi.yaml get /v1/public/workspaces/{workspace_id}/knowledge_bases
Returns knowledge bases scoped to the requested public API workspace.
# Search a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/search-a-knowledge-base
/openapi.yaml post /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}/search
Performs a vector, full-text, or hybrid search against the knowledge base.
Returns matching chunks above the configured score threshold.
# Update a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/update-a-knowledge-base
/openapi.yaml patch /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}
Updates name, description, or search settings of an existing knowledge base.
# List active models
Source: https://docs.fetchhive.com/api-reference/models/list-active-models
/openapi.yaml get /v1/public/models
Returns all active (non-deprecated) LLM and image-generation models
available in Fetch Hive as a flat array. Excludes embedding-only models.
`provider` identifies the underlying model maker (e.g. `openai`, `anthropic`, `minimaxai`).
`model_type` is `"llm"` for chat/text models and `"image_generation"` for
models that generate images. `is_vision` means a model accepts image input;
`is_image_generation` means a model generates images.
`is_reasoning` is `true` when the model supports reasoning capabilities.
# OpenAPI Spec
Source: https://docs.fetchhive.com/api-reference/openapi-spec
Download the Fetch Hive public API OpenAPI specification
The public API is described in an OpenAPI 3 document used to generate the REST API endpoint pages in this reference.
## Download
* [openapi.yaml](./openapi.yaml) — OpenAPI 3 specification for all `/v1/public/*` endpoints
Use this file with OpenAPI tooling, SDK generators, or API clients that import OpenAPI specs.
# Overview
Source: https://docs.fetchhive.com/api-reference/overview
Review authentication, invoke endpoints, errors, models, and API reference pages
Use the **API Reference** tab when you're calling Fetch Hive from your own app or service. It covers authentication, invoke endpoints, generated REST API pages, and error handling.
## Fetch Hive API
* [Authentication](./authentication) — Authenticate API requests with a workspace API key
* [Errors and rate limits](./errors-and-rate-limits) — Common error shapes, status codes, and concurrency behavior
* [Error codes](./error-codes) — Stable `error_code` values and the `GET /v1/error_codes` catalog
* [OpenAPI Spec](./openapi-spec) — Download the OpenAPI document for `/v1/public/*` endpoints
* [Invoke metadata](../user-tracking/invoke-metadata) — Attach caller-defined metadata to prompt, workflow, and agent invokes for log inspection and filtering
## REST API
Invoke endpoints and resource CRUD are grouped by product area in the sidebar under **REST API**:
| Resource | Invoke | Other endpoints |
| --------------- | ------------------------------ | ------------------------------------------------------- |
| Prompts | [Invoke](./prompts/invoke) | — |
| Workflows | [Invoke](./workflows/invoke) | — |
| Agents | [Invoke](./agents/invoke) | List, create, get, update, delete agents in a workspace |
| Hive Agents | [Invoke](./hive-agents/invoke) | — |
| Knowledge Bases | — | CRUD, items, search |
| Assets | — | List and upload |
| Models | — | `GET /v1/public/models` |
| Requests | — | `GET /v1/public/requests/{id}` |
| Search Services | — | Supported countries for search workflow steps |
# Invoke
Source: https://docs.fetchhive.com/api-reference/prompts/invoke
Run a prompt deployment with the public Fetch Hive API using a deployment name and variant
`POST /v1/prompt/invoke`
Run a prompt deployment from your own app or service.
## Authentication
Send your workspace API key in the `Authorization` header.
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Request body
Open **Prompts**, then **Deployments**, open the deployment variant you want to run, and click **Code Snippet** to see this request shape in Fetch Hive.
| Field | Type | Required | Description |
| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------- |
| `deployment` | string | Yes | The prompt deployment name |
| `variant` | string | Yes | The deployment variant name |
| `inputs` | object | No | Key-value pairs for the prompt variables |
| `streaming` | boolean | No | Stream response events instead of waiting for one final JSON response |
| `metadata` | object | No | Flat caller-defined metadata for audit and log filtering. This is not used as prompt input. |
`metadata` must be a flat object. Keys must be non-empty strings, and values must be strings, numbers, booleans, or `null`. Arrays and nested objects are rejected before the run starts.
`POST /v1/prompt/invoke` does not accept top-level `image_urls` or document
`attachments`. If a deployed prompt uses an image URL message part, configure
that image URL in the prompt editor or bind it through an `inputs` variable in
the prompt content. For runtime image/document attachments, use
[`POST /v1/agent/invoke`](../agents/invoke).
Valid:
```json theme={null}
{
"metadata": {
"customer_id": "cus_123",
"plan": "enterprise",
"trial": false,
"invoice_count": 12,
"region": null
}
}
```
Invalid:
```json theme={null}
{
"metadata": {
"customer": {
"id": "cus_123"
},
"tags": ["enterprise"]
}
}
```
## Response
If `streaming` is `true`, Fetch Hive returns a stream of events. If the provider fails after the stream has opened, Fetch Hive sends a final `error` event before closing the stream.
Example reasoning event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "reasoning",
"model": "gpt-5-nano",
"response": " seems"
}
```
Example response event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "response",
"model": "gpt-5-nano",
"response": " too"
}
```
Example final usage event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "usage",
"usage": {
"duration": 4.79230260848999,
"prompt_tokens": {
"total_tokens": 24,
"cached_tokens": 0,
"cached_read_tokens": 0,
"cache_write_tokens": 0
},
"completion_tokens": {
"total_tokens": 170,
"reasoning_tokens": 64
},
"total_tokens": 194
},
"stop_reason": "completed"
}
```
Example error event:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"type": "error",
"error": "cohere provider stream error: HTTP 400: invalid request",
"message": "cohere provider stream error: HTTP 400: invalid request",
"provider": "cohere",
"error_type": "provider_stream_error",
"status_code": 502
}
```
If `streaming` is `false`, Fetch Hive returns one JSON response. Provider execution failures return `502 Bad Gateway` with an `error` message.
```json theme={null}
{
"request_id": "req_019d528660dd7e22b15e5b13a1931c50",
"model": "gpt-5-nano-2025-08-07",
"duration": 4.641960144042969,
"reasoning": "The request asks for a short summary.",
"response": "Fetch Hive helps teams ship AI products faster.",
"usage": {
"prompt_tokens": {
"total_tokens": 24,
"cached_tokens": 0,
"cached_read_tokens": 0,
"cache_write_tokens": 0
},
"completion_tokens": {
"total_tokens": 187,
"reasoning_tokens": 64
},
"total_tokens": 211
},
"stop_reason": "completed"
}
```
## Example
```bash theme={null}
curl 'https://api.fetchhive.com/v1/prompt/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
"deployment": "YOUR_DEPLOYMENT_NAME",
"variant": "YOUR_VARIANT_NAME",
"inputs": {
"text": "Fetch Hive helps teams ship AI products faster."
},
"metadata": {
"customer_id": "cus_123",
"plan": "enterprise"
},
"streaming": true
}' \
--compressed
```
## Webhook trigger
`POST /v1/prompt/webhooks/{prompt_endpoint_id}/variants/{variant_id}`
Use a prompt webhook trigger when an external service should start a deployed prompt variant without a workspace API key. The request must include the prompt endpoint webhook secret in `X-Fetch-Hive-Webhook-Secret`. If a third-party tool cannot set custom headers, use `?secret=YOUR_WEBHOOK_SECRET` as a fallback.
Webhook prompt triggers always use callback delivery. Include `async.callback_url`; Fetch Hive returns `202` with `request_id` and `run_status: "running"`, then delivers either `prompt.completed` or `prompt.failed` to the callback URL.
```bash theme={null}
curl 'https://api.fetchhive.com/v1/prompt/webhooks/YOUR_PROMPT_ENDPOINT_ID/variants/YOUR_VARIANT_ID' \
-H 'X-Fetch-Hive-Webhook-Secret: YOUR_WEBHOOK_SECRET' \
-H 'Content-Type: application/json' \
--data-raw '{
"inputs": {
"text": "Fetch Hive helps teams ship AI products faster."
},
"metadata": {
"customer_id": "cus_123",
"plan": "enterprise"
},
"user": "external-user-1",
"async": {
"callback_url": "https://example.com/callback"
}
}'
```
`inputs` must be an object. Every variable declared on the selected deployed prompt version must be present, but values may be empty strings or `null` when you intentionally want a blank render. Extra input keys are allowed. `metadata` follows the same flat scalar-only rule as normal prompt invokes and appears in log filtering.
Fetch Hive signs the outbound callback with the same webhook secret used for inbound trigger authentication.
Callback `data` contains `response` on `prompt.completed` and `error` on `prompt.failed`; use the top-level `event_type` and `request_id` for terminal state and correlation.
## Related
* See [Authentication](./authentication) for API key setup
* See [Prompts](../prompts/overview) for prompt editor and deployment context
* See [Run with API](../prompts/run-with-api) for a prompt-focused guide
# Get a request
Source: https://docs.fetchhive.com/api-reference/requests/get-a-request
/openapi.yaml get /v1/public/requests/{id}
Returns the status, type, and timing metadata for a run.
Pass the `request_id` returned when you invoked a prompt, workflow, agent, or Hive Agent.
# List public search-service country catalogs
Source: https://docs.fetchhive.com/api-reference/search-services/list-public-search-service-country-catalogs
/openapi.yaml get /v1/public/search_services/countries
Returns the country catalogs used by public search workflow services.
This endpoint is unauthenticated and exposes the value each service expects for location/country configuration.
# Retrieve public search-service country catalog
Source: https://docs.fetchhive.com/api-reference/search-services/retrieve-public-search-service-country-catalog
/openapi.yaml get /v1/public/search_services/{service}/countries
Returns the country catalog for one supported search workflow service.
Use each country object's `value` field when configuring that service.
# Invoke
Source: https://docs.fetchhive.com/api-reference/workflows/invoke
Run a workflow deployment with the public Fetch Hive API using a deployment name, variant, and start inputs
`POST /v1/workflow/invoke`
Run a workflow deployment from your own app or service.
## Authentication
Send your workspace API key in the `Authorization` header.
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Request body
Open **Workflows**, then **Deployments**, open the deployment variant you want to run, and click **Code Snippet** to copy the current request shape from Fetch Hive.
| Field | Type | Required | Description |
| ------------ | ------ | -------- | --------------------------------------------------------------------------------------------- |
| `deployment` | string | Yes | The workflow deployment name |
| `variant` | string | Yes | The deployment variant name |
| `inputs` | object | No | Key-value pairs for the variables defined on the **Start** step |
| `async` | object | No | Callback delivery settings |
| `metadata` | object | No | Flat caller-defined metadata for audit and log filtering. This is not used as workflow input. |
`inputs` values are validated against the workflow's **Start** input definitions before the run starts. Array start inputs must be native JSON arrays, not JSON strings.
`metadata` must be a flat object. Keys must be non-empty strings, and values must be strings, numbers, booleans, or `null`. Arrays and nested objects are rejected before the run starts.
Valid:
```json theme={null}
{
"metadata": {
"customer_id": "cus_123",
"plan": "enterprise",
"trial": false,
"invoice_count": 12,
"region": null
}
}
```
Invalid:
```json theme={null}
{
"metadata": {
"customer": {
"id": "cus_123"
},
"tags": ["enterprise"]
}
}
```
If you include `async`, use these nested fields:
| Field | Type | Required | Description |
| -------------------- | ------- | ------------------------------------- | ------------------------------------------------------------- |
| `async.enabled` | boolean | Yes | Set to `true` to return immediately |
| `async.callback_url` | string | Yes when callback delivery is enabled | The callback URL Fetch Hive should call when the run finishes |
If you turn on **Callback delivery** in the code snippet dialog, Fetch Hive also shows a **Signing secret** for callback verification.
## Response
When callback delivery is off, Fetch Hive waits for the workflow to finish and returns the output in one response.
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"run_status": "completed",
"output": "State of enterprise AI in 2026: enterprises are moving from experimentation to operational systems with stricter evaluation, governance, and tooling requirements."
}
```
`output` is shape-dependent by workflow result type. For image-generation final outputs, `output` is an object with `settings` and `assets`:
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"run_status": "completed",
"output": {
"settings": {
"model": "grok-imagine-image-quality",
"provider": "xai",
"image_count": 1
},
"assets": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"file_url": "https://signed-download.example/...?X-Amz-Signature=...",
"file_url_expires_at": "2026-08-11T12:00:00Z",
"file_name": "step_3_123456789_1.png",
"file_size": 505042,
"file_type": "image/png"
}
]
}
}
```
When `async.enabled` is `true`, Fetch Hive returns immediately.
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"run_status": "running",
"webhook_secret": "YOUR_WEBHOOK_SECRET"
}
```
At high concurrency, Fetch Hive can also return a queued callback-delivery state.
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"run_status": "queued",
"webhook_secret": "YOUR_WEBHOOK_SECRET"
}
```
## Example
### Direct request
```bash theme={null}
curl 'https://api.fetchhive.com/v1/workflow/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
"deployment": "YOUR_DEPLOYMENT_NAME",
"variant": "YOUR_VARIANT_NAME",
"inputs": {
"topic": "State of enterprise AI in 2026"
},
"metadata": {
"customer_id": "cus_123",
"plan": "enterprise"
}
}' \
--compressed
```
### Callback delivery request
```bash theme={null}
curl 'https://api.fetchhive.com/v1/workflow/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
"deployment": "YOUR_DEPLOYMENT_NAME",
"variant": "YOUR_VARIANT_NAME",
"async": {
"enabled": true,
"callback_url": "https://example.com/callback"
},
"inputs": {
"topic": "State of enterprise AI in 2026"
}
}' \
--compressed
```
## Related
* See [Authentication](./authentication) for API key setup
* See [Callback Delivery and Webhook Triggers](../workflows/async-and-webhooks) for callback delivery and signature verification
* See [Run with API](../workflows/run-with-api) for a workflow-focused guide
# Run analytics
Source: https://docs.fetchhive.com/experiments/analytics
Compare run cost, token usage, latency, and success rate
Use run analytics on an experiment run detail page to compare how candidates performed inside that specific run.
Run analytics are calculated from stored experiment result cells. They do not re-run prompts, and they do not read the current source prompt configuration.
## Scope
Run analytics are scoped to one experiment run.
Use them when you want to compare candidates on the same dataset version and run conditions.
## Metrics
| Metric | Meaning |
| ---------------- | ------------------------------------------------------------------------ |
| Success rate | Completed result cells divided by all result cells in the selected scope |
| Total cost | Stored cost for all selected result cells |
| Average cost | Total cost divided by selected result cell count |
| Total tokens | Stored token usage for all selected result cells |
| Input tokens | Stored input token usage |
| Output tokens | Stored output token usage |
| Average tokens | Total tokens divided by selected result cell count |
| Average duration | Average duration for completed result cells |
| p95 duration | 95th percentile duration for completed result cells |
Failed result cells still count toward status totals. If a failed cell recorded cost or tokens before failing, those values remain included in cost and token totals.
Duration averages and percentiles only use completed result cells.
## Candidate charts
Candidate charts group results by experiment candidate.
Use these charts to compare:
* the cheapest candidate
* the fastest candidate
* the slowest candidate
* high-token candidates
* candidates with more failures
## Metadata filters
Analytics can be filtered by dataset row metadata.
For example, if your CSV includes `metadata.topic`, you can filter analytics to a specific topic and compare candidates only for those rows.
Metadata filters use dataset row metadata from the experiment run, not request metadata.
## TTFT
Time to first token is not shown in experiment analytics yet.
Fetch Hive currently shows reliable stored duration, cost, token, and status metrics for experiment results. TTFT will be added after first-token timing is captured consistently across dashboard prompts and deployed prompt invokes.
See also: [Review results](./results), [Run an experiment](./running-experiments), and [Datasets](./datasets)
# Build an experiment
Source: https://docs.fetchhive.com/experiments/building-experiments
Create an experiment, choose a dataset, and prepare candidates
Create an experiment when you want to compare one or more candidates against the same dataset.
## How do I create an experiment?
Open **Experiments**.
Click **Add Experiment**.
Enter a name and optional description.
Choose a dataset if you already have one.
Click **Add Experiment**.
You can also create the experiment first and attach or change the dataset before running.
## What should I add before running?
Before you start a run, make sure the experiment has:
* a dataset version
* at least one active candidate
* input columns that match the prompt inputs you expect to use
For prompts, make sure the dataset input column names match the prompt variables where possible.
## How should I name experiments?
Use names that explain the comparison.
Good examples:
* `Support FAQ prompt model comparison`
* `Invoice extraction prompt regression`
* `Refund policy prompt v3 vs deployed`
Avoid generic names such as `Test` or `Experiment 1`.
## Editing an experiment
Open the experiment.
Use the dropdown in the breadcrumbs to edit the experiment name or description.
Use **Archive** from the same menu when you no longer need the experiment in the main list.
Archived experiments are hidden from the default experiment list.
## Reproducibility
Experiments are designed to be repeatable.
Dataset versions are immutable. Candidates are captured as snapshots. This means a past run still points to the dataset rows and candidate configuration used at the time.
If you change a prompt later, add it as a new candidate or start a new experiment so the comparison remains clear.
See also: [Datasets](./datasets), [Add candidates](./candidates), and [Run an experiment](./running-experiments)
# Experiment candidates
Source: https://docs.fetchhive.com/experiments/candidates
Add dashboard prompts, deployed prompts, and agents to experiments
Candidates are the prompts or agents you want to compare in an experiment.
When you add a candidate, Fetch Hive captures the source configuration at that moment. Later edits to the source prompt or agent do not change the candidate already added to the experiment.
## Candidate types
| Candidate type | What it uses | When to use it |
| -------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------- |
| **Dashboard Prompt** | The current prompt from the dashboard editor | Use this when you are iterating on a prompt before publishing it. |
| **Deployed Prompt** | A prompt deployment, variant, and version | Use this when you want to test the exact version your app or API callers use. |
| **Agent** | An immutable snapshot of the agent configuration | Use this when you want each dataset row to run through the same agent setup. |
## How do I add a dashboard prompt?
Open the experiment.
Click **Add candidate**.
Choose **Dashboard Prompt** as the type.
Select the prompt.
Click **Add candidate**.
Use this when you want to compare the current prompt editor state.
## How do I add a deployed prompt?
Open the experiment.
Click **Add candidate**.
Choose **Deployed Prompt** as the type.
Select the prompt.
Select the deployed prompt.
Select the variant.
Select the version.
Click **Add candidate**.
Use this when you want repeatable testing against a specific production or staging deployment version.
## How do I add an agent?
Open the experiment.
Click **Add candidate**.
Choose **Agent** as the type.
Select the agent.
Click **Add candidate**.
Agent candidates run each dataset row as an isolated non-streaming call. They do not add messages to the source agent's dashboard chat history.
## Candidate settings
Candidate settings are read-only in experiments right now.
Edit model, temperature, tools, instructions, and other settings in the prompt or agent editor before adding the candidate.
Experiment-local overrides are planned for a future version.
## Refreshing a candidate snapshot
Use **Refresh snapshot** when the source prompt or deployed prompt has changed and you want future runs to use the latest source configuration.
Refreshing updates the existing candidate's captured snapshot. It does not change historical run results.
Use this when you want to keep the same candidate row in an experiment instead of archiving and re-adding it.
For deployed prompts, refresh uses the same selected deployment, variant, and version reference. If you want to test a different deployed version, add a new candidate for that version.
For agents, refresh captures the current agent configuration as a new snapshot for future runs. Historical run results remain unchanged.
## Archived candidates
If you archive a candidate, it is removed from future experiment setup and run selections.
Existing run results remain available so previous comparisons still make sense.
Archiving requires confirmation.
Older experiments may show unsupported legacy candidates. They remain visible for historical results, but new runs cannot include unsupported workflow snapshots. Archive unsupported candidates before starting a new run.
See also: [Prompts](../prompts/overview) and [Publishing and versioning](../prompts/publishing-and-versioning)
# Experiment datasets
Source: https://docs.fetchhive.com/experiments/datasets
Create CSV datasets for Fetch Hive experiments
Use **Datasets** to store reusable test cases for experiments.
Each dataset can have one or more immutable versions. When you run an experiment, Fetch Hive uses a specific dataset version so the run is repeatable.
## How do I create a dataset?
Open **Experiments**, then choose **Datasets** from the secondary navigation.
Click **Add Dataset**.
Enter a name and optional description.
Upload a CSV file. You can click the upload area or drag the CSV into it.
Review the column mapping. Fetch Hive automatically maps:
* normal columns to input values
* `expected_output` to expected output
* `metadata.*` columns to row metadata
Click **Add Dataset** to create the dataset and its first version.
## How do I view dataset versions?
Open **Experiments**, then choose **Datasets**.
Click a dataset row to open the dataset detail page.
Use the version selector in the page header to switch between versions. Versions are shown as labels like `v1`, `v2`, or `v4`.
The page URL includes the selected version:
```text theme={null}
/experiments/datasets/:datasetId/v/:versionId
```
Opening a dataset without a version selects the latest version automatically.
Runs always store the exact dataset version they used, so old runs remain reproducible even after newer dataset versions exist.
## CSV file format
The first row must contain column headers.
The CSV importer supports quoted values, commas inside quoted values, escaped quotes, multiline quoted values, and empty cells.
Upload limits:
| Limit | Value |
| -------------------------------- | ------ |
| File type | CSV |
| Maximum file size | 5 MB |
| Maximum rows | 10,000 |
| Preview rows shown in the dialog | 50 |
## CSV columns
An experiment dataset has three kinds of columns:
* input columns
* one optional expected output column
* optional metadata columns
Only input columns are needed to run candidates. Expected output and metadata are optional.
### Input columns
Input columns are the values Fetch Hive passes into the candidate for that row.
They do not have fixed names for prompt experiments. `question`, `context`, and `customer_message` are examples only. They are not required column names.
Use column names that match the candidate you are testing.
| Candidate type | What your CSV input columns should match | Example columns |
| ---------------- | ---------------------------------------------------------------- | -------------------------------------------------- |
| Dashboard Prompt | The prompt variables in the prompt editor | `question`, `context`, `input_url`, `input_scrape` |
| Deployed Prompt | The prompt variables captured in the selected deployment version | `question`, `context`, `input_url`, `input_scrape` |
| Agent | The agent user message | `message` |
At least one input column is recommended. Without an input column, the run has no row-specific input to send to the candidate.
For prompt experiments, the CSV input columns should match the prompt variables. If your prompt has `{{question}}` and `{{context}}`, your CSV should include `question` and `context`.
If your prompt has `{{input_url}}` and `{{input_scrape}}`, your CSV should include `input_url` and `input_scrape` instead.
For agent experiments, use a `message` input column for the user message. If there is no `message` column, Fetch Hive can use exactly one non-metadata input column as the message. Rows with multiple ambiguous input columns fail so you can fix the dataset.
### Expected output column
Use `expected_output` when you have a reference answer for the row.
| Column name | Required | Stored as | Notes |
| ----------------- | -------- | ----------------------- | ---------------------------------------------------------- |
| `expected_output` | No | `expected_output.value` | Used for manual review today and future evaluator scoring. |
Evaluator execution is not enabled yet. This means `expected_output` does not currently mark a result correct or incorrect automatically.
### Metadata columns
Use `metadata.*` columns for optional row labels.
Metadata columns do not trigger built-in behavior today. They do not change run order, model settings, locale, routing, or candidate execution. Fetch Hive stores them with the row so you can identify cases, filter results, compare groups, or connect results back to your own systems.
| Column pattern | Required | Stored as | Example |
| ------------------- | -------- | -------------------------------------- | ------------- |
| `metadata.case_id` | No | `metadata.case_id` becomes `case_id` | `geo-001` |
| `metadata.topic` | No | `metadata.topic` becomes `topic` | `geography` |
| `metadata.priority` | No | `metadata.priority` becomes `priority` | `high` |
| `metadata.source` | No | `metadata.source` becomes `source` | `support_faq` |
| `metadata.language` | No | `metadata.language` becomes `language` | `en` |
These names are examples only. You can use any `metadata.*` name that helps your team review results.
Do not use `meta_` prefixes for new datasets. Use `metadata.*` so the mapping is clear.
### Common CSV shapes
Prompt with `{{question}}`:
```csv theme={null}
question,expected_output,metadata.case_id,metadata.topic
"What is the capital of France?","Paris","geo-001","geography"
```
Prompt with `{{question}}` and `{{context}}`:
```csv theme={null}
question,context,expected_output,metadata.case_id,metadata.topic
"What is the refund window?","Customers can request a refund within 30 days.","30 days","policy-001","support"
```
Prompt with `{{input_url}}` and `{{input_scrape}}`:
```csv theme={null}
input_url,input_scrape,expected_output,metadata.case_id,metadata.topic
"https://example.com/pricing","The pricing page lists Starter, Pro, and Enterprise plans.","Summarize the three available plans.","scrape-001","pricing"
```
## Example CSV
You can download the example CSV from the **Add Dataset** dialog.
```csv theme={null}
question,context,expected_output,metadata.case_id,metadata.topic
"What is the capital of France?","Use only the provided context. France's capital city is Paris.","Paris","geo-001","geography"
"Who wrote Pride and Prejudice?","Jane Austen published Pride and Prejudice in 1813.","Jane Austen","lit-001","literature"
"What is 18 multiplied by 7?","Calculate the product exactly.","126","math-001","math"
"Which planet is known as the Red Planet?","Mars is often called the Red Planet because of iron oxide on its surface.","Mars","space-001","science"
"What HTTP status code means Not Found?","Common HTTP status codes include 200 OK, 404 Not Found, and 500 Internal Server Error.","404","web-001","web"
"Summarize the refund policy in one sentence.","Customers can request a refund within 30 days of purchase if they provide the original receipt.","Customers can request a refund within 30 days with the original receipt.","policy-001","support"
"Return the country code for Japan.","Use ISO 3166-1 alpha-2 country codes. Japan is JP.","JP","locale-001","localization"
"What color do you get by mixing blue and yellow?","In subtractive color mixing, blue and yellow make green.","Green","art-001","art"
"Extract the invoice total.","Invoice INV-1042 lists subtotal $90, tax $9, and total $99.","$99","invoice-001","finance"
"Classify the sentiment as positive, neutral, or negative.","The customer wrote: The setup was quick and the support team was helpful.","positive","sentiment-001","classification"
```
## Dataset versions
Dataset versions are immutable.
If you need to change rows later, create a new dataset version instead of editing a version already used by a run. This keeps old experiment runs reproducible.
## Importing rows
Use **Import** on the dataset detail page to append rows to a dataset.
Importing rows does not edit the current version. Fetch Hive creates a new immutable version that contains:
* all rows from the latest dataset version
* any new rows from the uploaded CSV
Duplicate rows are skipped. Duplicate detection compares the row's input values. Row position, expected output, and metadata do not make the same input row unique during import.
After import, Fetch Hive shows:
* imported row count
* skipped duplicate count
* the new latest dataset version
Example:
If `v3` has 100 rows and you import a CSV with 20 rows where 5 are duplicates, Fetch Hive creates `v4` with 115 rows.
Runs created before the import still point to their original dataset version. New runs can use the latest version.
See also: [Build an experiment](./building-experiments) and [Review results](./results)
# Experiment evaluators
Source: https://docs.fetchhive.com/experiments/evaluators
Current evaluator status and planned evaluator types for experiments
Evaluator execution is not enabled in the current experiments release.
Datasets can already store `expected_output`, but Fetch Hive does not yet run automatic scoring or pass/fail checks from it.
## Current behavior
When you upload a dataset, `expected_output` is stored with each row.
Use it during manual review and row comparison.
No exact-match evaluator runs automatically today.
## Planned evaluator types
Future evaluator support may include:
| Evaluator type | Use case |
| ----------------- | ---------------------------------------------------------------------------------------- |
| Exact match | Strictly compare output with expected output |
| Contains | Check whether output includes required text |
| Regex | Check output against a pattern |
| JSON field match | Compare specific fields in structured output |
| Schema validation | Confirm output follows a required JSON schema |
| LLM judge | Score semantic correctness, reasoning quality, instruction following, or task completion |
| Custom evaluator | Run workspace-defined evaluation logic |
## How should I prepare datasets for evaluators?
Add `expected_output` when you have a known answer.
Use `metadata.*` columns to group rows by topic, priority, source, language, or case id.
Keep expected outputs concise when you expect exact or contains checks.
Use structured JSON in `expected_output` when future field-level checks will be useful.
Example:
```csv theme={null}
question,expected_output,metadata.case_id,metadata.topic
"Return the country code for Japan.","JP","locale-001","localization"
```
See also: [Datasets](./datasets) and [Review results](./results)
# Overview
Source: https://docs.fetchhive.com/experiments/overview
Compare prompts and agents across datasets in Fetch Hive
Use **Experiments** when you want to compare prompts or agents against the same set of inputs.
An experiment lets you:
* upload or select a dataset
* add dashboard prompt, deployed prompt, and agent candidates
* run every dataset row against every candidate
* review outputs, usage, cost, and failures in one place
Experiments are useful when you want to test quality before publishing a change or compare models, prompt versions, deployed prompt variants, and agent configurations.
## What you'll find here
* [Datasets](./datasets) — Upload CSV files, map columns, and understand dataset format
* [Add candidates](./candidates) — Add dashboard prompts, deployed prompts, and agents
* [Build an experiment](./building-experiments) — Create an experiment and prepare it for a run
* [Run an experiment](./running-experiments) — Start, track, and cancel experiment runs
* [Review results](./results) — Compare outputs, open request details, and inspect failures
* [Run analytics](./analytics) — Compare run cost, tokens, latency, and success rate
* [Evaluators](./evaluators) — Understand current evaluator status and planned evaluator types
## How experiments work
An experiment combines a dataset with one or more candidates.
A **dataset** is a set of rows. Each row contains input values, optional expected output, and optional metadata.
A **candidate** is the prompt or agent you want to test. Fetch Hive captures a snapshot when you add the candidate so later edits to the source do not change that candidate inside the experiment.
A **run** executes the dataset against the candidates. If you have 100 dataset rows and three candidates, the run has 300 result cells.
Your current plan limits how many result cells a new run can create. Existing experiments and past runs remain available if your plan changes, but new runs must fit your current plan.
Each result cell stores the candidate output, status, duration, usage, cost, and links to request details when available.
## Current scope
Experiments currently run dashboard prompt drafts, prompt versions, deployed prompt versions, and agent snapshots.
Agent snapshots run as isolated single-shot calls. They do not write to the source agent's dashboard chat history, and each dataset row starts without memory from other rows. Workflow candidates, evaluator execution, experiment-local model overrides, and custom evaluator code are planned future additions. Existing unsupported legacy candidates may still appear in older experiments for history; archive them before starting a new run.
See also: [Prompts](../prompts/overview), [Publishing and versioning](../prompts/publishing-and-versioning), and [Log history](../monitoring/log-history)
# Experiment results
Source: https://docs.fetchhive.com/experiments/results
Review experiment outputs, failures, usage, and request details
Use run results to compare candidate behavior across dataset rows.
The default view is a result-cell table. Each row represents one dataset row run against one candidate.
## Result columns
Result tables can include:
| Column | Meaning |
| -------------- | -------------------------------------------------------------------- |
| Dataset row | The row position from the dataset version |
| Candidate | The prompt candidate |
| Status | Pending, running, completed, failed, cancelled, or another run state |
| Output preview | Short preview of the generated output |
| Duration | Time spent on the result cell |
| Tokens | Token usage when available |
| Cost | Cost recorded for the result cell |
| Metadata | Dataset row metadata, shown as a compact count with a hover detail |
| Request ID | The linked request created by the normal prompt execution flow |
## How do I filter results?
Use the filters at the top of the result view.
You can filter by candidate, status, dataset row, or text search.
Use filters when you want to focus on failures, compare one candidate at a time, or inspect a specific case.
## How do I export results?
Click **Export CSV** from the run results table.
The export includes every result that matches the current filters, not only the visible page.
CSV exports include dataset inputs, expected output, metadata, candidate details, output or error text, request IDs, timing, token usage, cost, and timestamps.
## How do I inspect a result?
Click a result row.
Fetch Hive opens the same request detail sheet used by the normal logs area. This keeps experiment review aligned with live prompt request inspection instead of using a separate experiment-only detail surface.
Use request details when you need provider settings, inputs, metadata, trace availability, cost, timing information, or completions.
If a result failed before a request was created, the row remains visible with the failure status and any stored output or error summary.
## How expected output appears
If the dataset row includes `expected_output`, use it as the reference answer while reviewing results.
Evaluator execution is not enabled yet. This means Fetch Hive does not currently mark a result correct or incorrect automatically.
See also: [Datasets](./datasets), [Run an experiment](./running-experiments), and [Log history](../monitoring/log-history)
# Run an experiment
Source: https://docs.fetchhive.com/experiments/running-experiments
Start, track, and cancel experiment runs
An experiment run executes each dataset row against each active candidate.
If your dataset has 250 rows and the experiment has four candidates, the run creates 1,000 result cells.
Your current plan limits how many result cells a new run can create:
* Developer: 50 result cells
* Growth: 250 result cells
* Pro: 1,000 result cells
* Enterprise: 5,000 result cells
If your plan changes, existing experiments and past runs remain available. New runs use your current plan limit, so a run that fit on Pro may need fewer dataset rows or candidates after a downgrade.
## How do I start a run?
Open the experiment.
Click **Start run**.
Confirm the dataset version.
Review the candidate count and total result cells.
Click **Start run**.
## Billing and usage
Experiment generations use normal model execution and billing.
The total run cost depends on:
* dataset row count
* candidate count
* model settings
* tool usage
* retries or failures that still produce billable provider work
Review the result cell count before starting large runs.
## Tracking progress
While a run is active, Fetch Hive shows run status, phase, completed count, failed count, pending count, token totals, cost, and duration.
Runs may take time when datasets are large or candidates use slower models or tools.
Agent snapshot candidates can take longer than prompt candidates because they may call tools. Fetch Hive runs those cells with longer worker timeouts and keeps each row isolated from source agent chat history.
Each run has a stable run ID such as `exrun_a1b2c3d4e5f6`. Use this ID when sharing a run link with your team or when matching dashboard activity back to API responses.
## Cancelling a run
Open the run.
Click **Cancel run** when the run is still pending or running.
Cancellation stops remaining work where possible. Results already completed remain available.
## Failed cells
A failed result cell does not always mean the whole run failed.
Open the result detail to review the error. Common causes include missing inputs, unavailable models, provider failures, tool failures, or configuration issues in the candidate.
See also: [Review results](./results) and [Task costs](../resources/task-costs)
# Creating & Editing
Source: https://docs.fetchhive.com/knowledge-base/creating-and-editing
Create a knowledge base, add content items, process them into chunks, and manage search settings
Create a knowledge base when you want Fetch Hive to store content that can be searched by workflows and agents.
## Overview
The **Knowledge Bases** page lists your active knowledge bases. Each row shows the knowledge base name, search type, and item count. Open a knowledge base to view analytics, add items, test search behavior, and edit the content that Fetch Hive stores as searchable chunks.
Knowledge bases can also be used from workflow steps and agent tools. Use [Write to Knowledge Base](../workflows/steps/knowledge-base/write-knowledge-base) to add content from a workflow, [Search Knowledge Base](../workflows/steps/knowledge-base/search-knowledge-base) to retrieve chunks in a workflow, or [Vector Search](../agents/mcp-tools/vector-search) to let an agent search a knowledge base.
## How do I create a knowledge base?
1. Open **Knowledge Bases** from the sidebar.
2. Click **Add Knowledge Base**.
3) Enter a **Name**.
4) Add an optional **Description**.
5) Choose a **Search Type**:
* **Hybrid** combines semantic and keyword matching.
* **Vector** uses semantic similarity.
* **Full Text** uses keyword search.
6) Set **Search Chunk Limit** to control how many matching chunks search returns by default. New knowledge bases start at **8**.
7) Set **Score Threshold** to filter out lower-confidence matches. New knowledge bases start at **0.1**, which works well for hybrid search (including Hive Agents). Higher values such as **0.5** can return zero chunks.
8) Click **Save**.
Fetch Hive opens the knowledge base detail page after it creates the knowledge base.
## How do I edit knowledge base settings?
Open a knowledge base from the **Knowledge Bases** list.
Use the breadcrumb menu next to the knowledge base name and choose the edit action.
Update **Name**, **Description**, **Search Type**, **Search Chunk Limit**, or **Score Threshold**.
Click **Save Changes**.
These settings become the default search behavior for the knowledge base. You can still override search settings when you run a test search or configure a workflow search step or agent Vector Search tool.
## How do I add an item?
Open a knowledge base and click **Add Item**.
Enter a **Name** and optional **Description**.
Choose an **Item Type**:
* **Custom Text** - Paste or type text content directly.
* **Document Upload** - Upload a file such as a PDF, Word document, text file, markdown file, CSV, or spreadsheet.
* **Website Scrape** - Scrape content from a URL.
Click **Save**.
Fetch Hive opens the item editor after it creates the item.
For document items, uploaded files are stored as account assets. See [Media library](../workspace/media-library) for how to browse shared files in your account.
## How do I edit and process an item?
Open an item from the knowledge base item table.
Update the item fields you need:
* **Name** and **Description** for item metadata.
* **Content** for **Custom Text** items.
* **Website URL** and **Response Type** for **Website Scrape** items.
* **Document** for **Document Upload** items.
* **Chunking Strategy** for how Fetch Hive splits content before embedding.
* **Remove Email Addresses** and **Remove Phone Numbers** when content may include personal data.
Click **Save** to store your changes.
Click **Process** to generate searchable chunks.
The item editor shows the current status, generated chunks, total tokens, and cost. While an item is processing, Fetch Hive disables editing actions that would conflict with the run. If processing fails, the editor shows the error message.
## How do I control chunking?
Use **Chunking Strategy** in the item editor.
Leave it set to **Default** for most items. Fetch Hive uses deterministic chunking that preserves paragraph and sentence boundaries where possible, favors speed, and avoids duplicate chunks.
Choose **Advanced** when you need manual control. Set **Maximum Chunk Length** and **Chunk Overlap** before you process the item. Advanced uses the same boundary-aware chunking as Default, then applies overlap to preserve context between adjacent chunks. For long documents or Hive Agents, about **1500** maximum chunk length is a strong starting point.
Larger chunks can preserve more context. Smaller chunks can make search results more focused. Use **Testing a Knowledge Base** when you want to check how the chunks behave in search. Re-process the item after you change chunk settings.
## How do I delete content?
To delete an item, open it in the item editor and click the delete action. Confirm the deletion in the dialog.
To archive a knowledge base, open the breadcrumb menu on the knowledge base detail page and choose the archive action. Confirm the archive in the dialog.
Deleting an item removes its associated vector embeddings. Archiving a knowledge base removes it from the active **Knowledge Bases** list.
See also: [Testing a Knowledge Base](./testing-a-knowledge-base) and [Logs](./logs)
# Logs
Source: https://docs.fetchhive.com/knowledge-base/logs
Review knowledge base processing runs, filter activity, and inspect run details
Knowledge base logs show processing activity for knowledge base items. Use them to review custom text, document upload, and website scrape runs after content is processed.
## Overview
Knowledge base logs live under **Logs** in the knowledge bases section menu. The page centers on a paginated table of runs. Click a row to open the run detail sheet and inspect the selected run.
This page covers item processing logs. For search testing, use [Testing a Knowledge Base](./testing-a-knowledge-base).
## How do I open knowledge base logs?
1. Open **Knowledge Bases** from the sidebar.
2. Click **Logs** in the knowledge bases section menu.
Fetch Hive opens the knowledge base logs table.
## What's tracked in the logs table?
The main logs table shows summary fields for each processing run, including:
* **Started**
* **Knowledge Base**
* **Item**
* **Type**
* **Status**
* **Total Tokens**
* **Total Cost**
* **Duration**
* **API Key**
* **Collaborator**
The **Type** column shows whether the run processed **Custom**, **Document**, or **Website** content. The **Status** column shows whether the run is pending, running, completed, or failed.
## How do I filter knowledge base logs?
Use the date range control in the header to choose the time window you want to inspect.
Use **Knowledge Base** to filter the table to one knowledge base.
Use **API Keys** to filter runs by the API key associated with the run.
Use the **Type** section in the sidebar to filter by:
* **All Types**
* **Custom**
* **Document**
* **Website**
Click **Clear filters** when you want to reset active table filters. Use **Columns** when you want to hide or restore table columns.
## How do I inspect a processing run?
Click a row in the logs table.
Fetch Hive opens the run detail sheet. The sheet shows the run status, request details, cost and token usage, related completions, and any error message for a failed run.
When trace data is available, the detail sheet includes a waterfall timeline for the processing run. Select spans such as document loading, website scraping, PII removal, chunking, or embedding to inspect timing, metadata, request details, and related completion output.
If the related knowledge base or item still exists, the detail sheet links back to that knowledge base or item editor.
Use the detail sheet when you need to understand why processing failed, which step took time, how many tokens it used, or which item generated the run.
## Notes
* Logs are for processing runs, not every search query.
* Date range availability can depend on your workspace plan.
* Document uploads can also appear in the [Media library](../workspace/media-library) as account assets.
* Workflow writes can create knowledge base items. See [Write to Knowledge Base](../workflows/steps/knowledge-base/write-knowledge-base) for the workflow path.
# Overview
Source: https://docs.fetchhive.com/knowledge-base/overview
Create searchable knowledge bases, add content, test search behavior, and review activity logs
Knowledge bases store content that Fetch Hive can chunk, embed, search, and use in workflows or agent tools. Use them when you want prompts, workflows, or agents to retrieve context from your own documents, text, or websites.
## What you'll find here
* [Creating & Editing](./creating-and-editing) - Create a knowledge base, add items, process content, and manage search settings
* [Testing a Knowledge Base](./testing-a-knowledge-base) - Run test searches and tune search settings before using a knowledge base elsewhere
* [Logs](./logs) - Review knowledge base processing runs, filters, costs, and run details
# Testing a Knowledge Base
Source: https://docs.fetchhive.com/knowledge-base/testing-a-knowledge-base
Run test searches, inspect matching chunks, and tune search settings before using a knowledge base
Use **Test Search** to check how a knowledge base responds before you connect it to a workflow or agent.
## Overview
The knowledge base detail page includes a **Test Search** action in the header. It opens a side sheet where you can enter a query, override search settings, and review the chunks that match your query.
Test searches use the selected knowledge base. They do not create or change knowledge base items, but they do create search activity that appears in knowledge base analytics and search records.
## How do I run a test search?
1. Open **Knowledge Bases** from the sidebar.
2. Open the knowledge base you want to test.
3. Click **Test Search** in the header.
4) Enter a **Search Query**.
5) Choose a **Search Type**.
6) Set **Chunk Limit**.
7) Set **Score Threshold**.
8) Click **Run**.
Fetch Hive shows matching chunks in the sheet after the search completes.
## How do I read test results?
Each result card shows the returned chunk content and a match score. Higher scores mean the chunk is a stronger match for the query.
Use the collapse action on a result card when you want to scan results quickly.
If no results appear, try a broader query, lower **Score Threshold** (empty results often mean the threshold is too high), or increase **Chunk Limit**.
If results are too broad, raise **Score Threshold** or switch **Search Type**. **Hybrid** is the recommended starting point. **Vector** is useful for conceptual matches. **Full Text** is useful for exact words or phrases.
## How do I tune search settings?
Start with the knowledge base defaults:
* **Search Type** set to **Hybrid**
* **Chunk Limit** set to **8**
* **Score Threshold** set to **0.1**
Run a few realistic queries. Review whether the returned chunks contain enough context for the workflow or agent that will use them.
Increase **Chunk Limit** when answers need more source context. Raise **Score Threshold** when too many weak matches appear. Lower **Score Threshold** when relevant chunks are missing.
After you find a better default, edit the knowledge base settings from the knowledge base detail page.
## Where do test searches show up?
Test searches are stored as knowledge base search activity. The detail page analytics update after test searches run, including total searches and average search duration for the selected date range.
Use [Logs](./logs) for processing runs such as custom text, document upload, and website scrape activity. Use the knowledge base detail analytics when you want a quick view of search volume and search duration.
See also: [Search Knowledge Base](../workflows/steps/knowledge-base/search-knowledge-base) and [Vector Search](../agents/mcp-tools/vector-search)
# Analytics
Source: https://docs.fetchhive.com/monitoring/analytics
Use Dashboard analytics to review workspace cost, token usage, service mix, model mix, trace performance, and top users
Use Fetch Hive analytics when you want a workspace-level view of cost, token usage, trace performance, and the users driving activity.
## Overview
The main analytics view in Fetch Hive lives under **Dashboard**. It gives you a shared monitoring surface for spend, service mix, model mix, model reliability, trace performance, token usage, and top users over a selected time range.
This page is different from the dedicated **Users** analytics view. **Dashboard** analytics is the wider workspace report, while the **Users** section focuses on tracked end-user activity.
## How do I open workspace analytics?
Open **Dashboard** in the main sidebar, then click **Analytics** in the secondary navigation.
Fetch Hive loads the analytics cards and charts for your current workspace. Switching workspace changes the analytics totals and charts to that workspace's data.
## What metrics and charts are available?
The analytics page currently shows seven monitoring panels:
* **Total Cost** for workspace spend over the selected period
* **Service Costs** for the mix of services that generated cost
* **Model Costs** for LLM and image-generation model usage and spend
* **Model Observability** for model latency percentiles and error rate
* **Trace Performance** for run latency, span bottlenecks, and tool usage
* **Token Usage** with totals for input, cached, reasoning, citation, image, and output tokens
* **Top Users** so you can rank tracked users by activity
Use **Service Costs** when you want to see which services contribute to spend.
Use **Model Costs** when you want to compare LLM and image-generation model usage, token volume, and cost in one place.
Use **Model Observability** when you want to compare model latency and failure rate across prompt calls, agent calls, workflow prompt-step calls, and image-generation model calls.
Use **Trace Performance** when you want to compare timed trace span groups, slow timed reasoning models, slow timed tools, slow timed workflow tools called by agents, and average tool count per run. Trace timing is observed from Fetch Hive's platform boundary, so provider spans show Fetch Hive-observed round-trip or stream-phase timing rather than provider-internal telemetry. Structural tool markers without provider timing still count as tool usage, but they are excluded from duration shares and slow-tool rankings.
Where analytics split cost into **Task credits** and **Wallet**, task credits are an estimated platform cost based on included plan tasks or purchased top-up tasks. Wallet is the hosted LLM wallet portion.
Open **Show all** from **Model Costs** when you need the full model-cost table for the selected date range.
Use **Token Usage** when you want to inspect how token volume is split across input, cached, reasoning, citation, image, and output tokens. Image tokens include image-input tokens and generated-image output tokens when the provider returns token usage.
In **Top Users**, you can switch between **Cost** and **Requests**.
## How do I change the reporting window?
Use the date-range control in the header to switch between the preset ranges or choose a custom range.
When you apply a new range, Fetch Hive refreshes every analytics panel for that period.
## How do I drill into a user from analytics?
Use **Top Users** when you want to move from a workspace report into a specific tracked user.
Click a user in the chart to open that user's detail page under **Users**.
From there, you can inspect that user's activity and open the underlying prompt, workflow, or agent run details.
## Analytics vs user tracking
Use this page when your question starts at the workspace level, such as:
* Which services are driving cost?
* Which models are responsible for the most spend?
* Which models are slow or failing most often?
* Which trace span types or tools are slowing down runs?
* How much token volume did this workspace generate?
Use the **Users** section when your question starts with a specific tracked end user or a user activity trend.
See also: [User tracking analytics](../user-tracking/analytics).
# Credit Usage
Source: https://docs.fetchhive.com/monitoring/credit-usage
See where Fetch Hive shows cost, tokens, and credit-related usage details across analytics, logs, and run details
Use the credit and usage views in Fetch Hive when you want to understand where spend, tokens, and run-level usage appear in the product.
## Overview
Fetch Hive shows usage in more than one place. **Dashboard** analytics gives you the workspace-level view, while log tables and run detail sheets show usage for individual prompt, workflow, chat Agent, Hive Agent, and knowledge base runs.
## Where do I see credit usage across the workspace?
Open **Dashboard** in the main sidebar, then click **Analytics**.
This page gives you workspace-level usage views such as **Total Cost**, **Service Costs**, **Model Costs**, and **Token Usage**.
## How do I inspect cost and token usage for an individual run?
Open **Prompts**, **Workflows**, **Agents**, **Hive Agents**, or **Knowledge Bases**, then click **Logs**.
Prompt and chat Agent logs show **Total Tokens**, **Total Cost**, and **Duration** in the main table. Workflow logs show **Total Cost** and **Duration**. Hive Agent logs show **Total Tokens**, **Total Cost**, **Duration**, **Pass**, **Nodes**, and **Sources**.
Click a row to open the detail sheet. Hive Agent details also show source preparation costs, node attempt costs, planner cost, verifier cost, and budget events when available. The request-sheet summary shows task, token, and cost hover breakdowns by node run so you can see which planned work node drove usage.
## What's included in Hive Agent totals?
Hive Agent run totals include source preparation, planning, execute attempts, verify attempts, and child AgentRun costs linked to those stages.
Budget checks use cumulative run cost plus projected cost when available. If a run repeats rejected nodes, later passes add more execution and verification cost.
## Notes
* Task credit cost is an estimate, not a separate plan invoice charge for each run.
* These views show usage signals in the product UI. Check your plan or billing terms separately for pricing and billing rules.
* If you want the full log and trace workflow, see [Log History](./log-history).
* For Hive Agent-specific spend controls, see [Budget Approval](../hive-agents/budget-approval).
# Log History
Source: https://docs.fetchhive.com/monitoring/log-history
Open prompt, workflow, agent, Hive Agent, and knowledge base logs in Fetch Hive and inspect filters, run details, and traces
Use log history in Fetch Hive when you want to review individual prompt, workflow, chat Agent, Hive Agent, or knowledge base runs and inspect what happened during a request.
## Overview
Fetch Hive gives you separate log views for prompts, workflows, chat Agents, Hive Agents, and knowledge base processing. Each view starts with a table of runs, then lets you open a detail sheet for deeper trace and run-level inspection.
For the Hive Agent-specific walkthrough, see [Hive Agent Logs](../hive-agents/logs).
## How do I open logs for prompts, workflows, agents, or Hive Agents?
Open one of these sections in the main sidebar:
* **Prompts**
* **Workflows**
* **Agents**
* **Hive Agents**
* **Knowledge Bases**
Then click **Logs** in the secondary navigation.
Prompt, workflow, chat Agent, and Hive Agent logs expose a **Source** section in the secondary navigation. Hive Agent logs use a workspace-wide run table and let you switch between **All Sources**, **Dashboard**, and **API** runs.
If you already have a full request ID, paste the `req_...` value into global search and choose **Go to request**.
## How do I filter logs?
These log pages use the date-range control, pagination, and column visibility controls in the table.
Each log page also has its own filter set:
* **Prompts** logs support **Provider**, **Model**, **API keys**, and **Prompt**
* **Workflows** logs support **API keys**, **Workflow**, source navigation, and **Delivery**
* **Agents** logs support **Provider**, **Model**, **API keys**, and source navigation
* **Hive Agents** logs support **Hive Agent**, **Status**, source navigation, and text search by Hive Agent name, objective, or request ID
* **Knowledge Base** logs support **Knowledge Base**, **API keys**, and **Type**
## What's tracked
Depending on the resource type, Fetch Hive shows combinations of completion time, resource name, provider, model, tool usage, objective, node count, source count, status, total cost, total tokens, duration, API key, collaborator, and request ID.
Hive Agent logs show **Hive Agent**, **Objective**, **Status**, **Pass**, **Nodes**, **Sources**, **Total Tokens**, **Total Cost**, **Duration**, **API Key**, and **Collaborator**.
## How do I read a run detail sheet?
Click a row in the logs table to open the matching detail sheet.
The sheet starts with a header, a status, and a summary strip. The detail panel can include response content, request details, inputs, metadata, output sections, trace spans, and run-specific fields.
## Traces
When a run has a trace, Fetch Hive shows a waterfall panel on the left side of the detail sheet.
Use this panel to move through the run step by step. Selecting a span updates the detail panel so you can inspect that span's timing, input, output, metadata, cost, tokens, or tool details.
Hive Agent traces show source preparation, planning, execution, verification, repeat decisions, budget checks, retryable stage errors, and final completion or cancellation. Run-level failure messages stay on the overview and terminal spans, allowed budget checks stay informational, and planner, executor, and verifier stages can expand to show child AgentRun reasoning, LLM responses, and tool panels inline.
When a Hive Agent is cancelled with a partial result, the run remains `cancelled` but keeps verified node output in the run details.
## Notes
* The trace waterfall appears when trace data is available.
* You can also open these same detail sheets from **Users** after drilling into a tracked end user.
* For Hive Agent status meanings and node details, see [Hive Agent Logs](../hive-agents/logs).
# Overview
Source: https://docs.fetchhive.com/monitoring/overview
Review analytics, credit usage, logs, traces, and troubleshooting views
This section covers the monitoring surfaces in Fetch Hive that help you understand usage, inspect runs, and troubleshoot what happened during a request.
Use these pages when you want to review workspace-level analytics, check where cost and token usage appear in the product, or open prompt, workflow, chat Agent, Hive Agent, and knowledge base logs with trace details.
## What you'll find here
* [Analytics](./analytics) - Use **Dashboard** analytics to review total cost, service costs, model costs, model observability, token usage, and top users across your workspace
* [Credit Usage](./credit-usage) - See where Fetch Hive shows cost, tokens, and credit-related details in analytics, logs, and run detail sheets
* [Log History](./log-history) - Open prompt, workflow, chat Agent, Hive Agent, and knowledge base logs, apply filters, and inspect traces
If you want Hive Agent-specific run details, start with [Hive Agent Logs](../hive-agents/logs).
# Get in contact
Source: https://docs.fetchhive.com/resources/get-in-contact
Book a Fetch Hive demo or send a message through the public contact form
Use these links when you want to speak with the Fetch Hive team.
* [Book a demo](https://cal.com/fetchhive/product-demo) — Schedule a product demo
* [Contact Fetch Hive](https://hey.jotjab.com/forms/2a0632e5631522bbd8ae0d27463c8b30321e) — Send a message through the contact form
# Model library
Source: https://docs.fetchhive.com/resources/model-library
The current Fetch Hive model library
The current Fetch Hive model library is maintained at:
[https://fetchhive.com/model-library](https://fetchhive.com/model-library)
Only active models appear in the model library and model selectors. Resources saved with retired models remain editable, but Fetch Hive shows an unavailable-model warning and blocks runs with `model_deprecated` until you choose a current model.
Signed-in users can open **Tools > Compare Models** in any workspace to compare
active language models side by side. The comparison uses the current Fetch Hive
model catalog for capabilities, context windows, and provider list prices in USD
per 1 million tokens. Hosted-wallet usage passes these recorded provider prices
through without a per-call markup; platform task credits remain separate.
When a provider bills cache creation separately, the comparison lists **Cache
write** independently from ordinary input and cached reads. Completion logs use
the same active-catalog rates and show the provider-reported cache-write tokens
and cost. Hosted runs debit the LLM wallet for the complete provider charge,
including cache writes, with no additional hosted-model markup.
Some models use token-length pricing tiers. Each comparison row shows the short
rate at or below the model threshold and the long rate above it. When a request
crosses the threshold, the long card prices the complete request, including
input, cached tokens, cache writes, and output. Prompt and agent completion logs
show which tier was applied, and hosted LLM wallet charges use that same card.
# Overview
Source: https://docs.fetchhive.com/resources/overview
External references and product reference pages for models, updates, contact, and security information
This section collects public reference pages and external links you may need while working with Fetch Hive.
## What you'll find here
* [Model library](./model-library) — Review the models currently available in Fetch Hive by provider
* [Task costs](./task-costs) — Review task credit costs by Fetch Hive service
* [Changelog](./changelog) — Open the public changelog for product updates
* [Roadmap](./roadmap) — Open the public roadmap and feedback board
* [Security and compliance](./security-and-compliance) — Review public privacy, data handling, and provider access references
* [Get in contact](./get-in-contact) — Book a demo or send a message to the team
# Roadmap
Source: https://docs.fetchhive.com/resources/roadmap
View the public Fetch Hive roadmap and feedback board
Fetch Hive uses its public Canny board for roadmap visibility and product feedback.
* [Open the Fetch Hive roadmap](https://fetch-hive.canny.io/)
You can review current requests and product discussions there.
# Security and compliance
Source: https://docs.fetchhive.com/resources/security-and-compliance
Public references for Fetch Hive privacy, data handling, retention, and model provider access
Use this page when you need public references for how Fetch Hive handles privacy, retention, and third-party model access.
## Privacy and data handling
Fetch Hive's public [Privacy Policy](https://fetchhive.com/privacy) describes the categories of personal information and business data it collects and processes.
The policy states that personal information and business data are stored and processed in the European Economic Area or in facilities used by partners, affiliates, and third-party providers. It also states that appropriate safeguards are used when data is transferred outside the EEA.
The public retention periods listed in the policy are:
* Account information: while your account is active, plus 24 months after account closure
* Payment information: for as long as required by applicable financial and tax regulations
* Communication data: 24 months after the last communication
* Log and analytics data: 12 months from collection
## Workspace data isolation
Fetch Hive enforces workspace-level data isolation at the database layer using PostgreSQL Row-Level Security (RLS). Every request runs in the context of the authenticated user's workspace, and the database itself restricts reads and writes to records belonging to that workspace.
This means workspace data is segregated defence-in-depth: even if application-level checks were bypassed, the database would still prevent access to data from other workspaces. This applies across the platform, including agents, workflows, runs, knowledge bases, documents, and API keys.
## AI model providers
Fetch Hive currently exposes models from these providers in the product:
* OpenAI
* Anthropic
* Google
* xAI
* Perplexity
* Cohere
* DeepSeek
You can review the current provider and model list in [Model library](./model-library).
If you use **Personal** charge type, connect provider credentials through [Integrations](../workspace/integrations). See [Use your own API Key](../workspace/llm-providers) for that setup flow.
## Policy references
The public Privacy Policy states that Fetch Hive is GDPR compliant and that its use of Google API data adheres to the Google API Services User Data Policy, including Limited Use requirements.
The same policy also lists third-party processor categories used for analytics tracking, user authentication, advertising and promotion, email marketing, and payment processing.
## Contact
For privacy, data protection, or policy questions, use the contact details listed in the [Privacy Policy](https://fetchhive.com/privacy) or the general [Get in contact](./get-in-contact) page.
# Task costs
Source: https://docs.fetchhive.com/resources/task-costs
Task credit costs by Fetch Hive service
Fetch Hive tracks task costs by service. Most services have a fixed task credit cost. Some depend on provider usage, search depth, account model type, or number of generated images.
## How task costs work
Hosted AI model calls, hosted agent calls, hosted prompt runs, hosted native search, and hosted image generation use the hosted LLM pool for provider usage. Each call still records a task count.
Personal model calls use your connected provider account. They charge the platform task credits shown in the table and don't add a hosted provider charge.
Metered hosted tools (Google Search, Bing Search, Google News, Google AI Mode, Website Scrape, Exa Search, Exa Similar, and Perplexity Search) convert the recorded service cost plus a **6% service fee** into task credits. Logs show those two USD figures separately so you can see exactly what the provider charged and what Fetch Hive added. They explain the task-credit charge; they are not billed on top of it. This 6% service fee is separate from the 6% fee charged when you top up the Hosted LLM Wallet.
## Workflow and model services
| Service | Task credits | Notes |
| -------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AI Model | 1 | Hosted calls also include provider usage in the hosted LLM pool. Personal model calls cost 1 platform task credit. |
| Agent | 1 | Hosted agent calls also include provider usage in the hosted LLM pool. Personal model calls cost 1 platform task credit. |
| Prompt | 1 | Prompt runs use the same pricing path as AI model calls. |
| Image Generation | 1 per image | Hosted image generation charges one task per generated image and includes provider usage in the hosted LLM pool. Personal image generation costs one platform task credit per image. |
| Google Search | Variable | Hosted searches convert the recorded service cost plus a 6% service fee into task credits. Backup search costs 3 credits. Personal searches cost 0 credits. |
| Google Grounding | 1 | Hosted Gemini grounded results charge one task and provider usage in the hosted LLM pool. Personal Gemini grounding records the tool run without hosted LLM wallet credits. |
| Bing Search | Variable | Uses the same task cost rules as Google Search. |
| Google News | Variable | Uses the same task cost rules as Google Search. |
| Google AI Mode | Variable | Hosted searches convert the recorded service cost plus a 6% service fee into task credits. Personal provider usage costs 0 credits. |
| Google AI Overview | 2 | Personal provider usage costs 0 credits. |
| Website Scrape | Variable | Hosted scrapes convert the recorded service cost plus a 6% service fee into task credits. |
| Exa Search | Variable | Hosted calls convert the Exa service cost plus a 6% service fee into task credits. Personal calls cost 1 credit. |
| Exa Similar | Variable | Hosted calls convert the Exa service cost plus a 6% service fee into task credits. Personal calls cost 1 credit. |
| Perplexity Search | Variable | Hosted calls use the fixed \$0.005 Search API request cost plus a 6% service fee. Personal calls cost 1 platform task. |
| Copilot Search | 5 | Fixed platform task credit cost. |
| Custom API | 1 | Fixed platform task credit cost. |
| Slack | 1 | Fixed platform task credit cost. |
| Notion | 1 | Fixed platform task credit cost. |
| Google Docs | 1 | Fixed platform task credit cost. |
| Google Sheets | 1 | Fixed platform task credit cost. |
| Generate File | 1 | Fixed platform task credit cost. |
| URL to Screenshot | 1 | Fixed platform task credit cost. |
| Airtable | 1 | Fixed platform task credit cost. |
| Linear | 1 | Fixed platform task credit cost. |
| Google Calendar | 1 | Fixed platform task credit cost. |
| Write to Knowledge Base | 1 | Fixed platform task credit cost. |
| Search Knowledge Base | 1 | Fixed platform task credit cost. |
| Embedding | 1 | Embeddings use `text-embedding-3-small` by default. |
| Document URL | 0 | Fixed platform task credit cost. |
| Document Upload | 0 | Fixed platform task credit cost. |
| JSON Schema | 0 | Fixed platform task credit cost. |
| Custom Knowledge Base Item | 0 | Fixed platform task credit cost. |
## Agent tool calls
Agent tool calls are billed when the agent run records each completed tool call. Sub-agents bill through their child agent run instead of the parent tool call. Nested sub-agent costs, tokens, and task credits roll up through the parent chain, including failed child runs when they produced billable completion records. Execution timeout and depth/parallelism caps are controlled separately from trace and cost rendering.
| Agent tool | Task credits | Notes |
| -------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| GPT Search | 1 | Native OpenAI web search is recorded as a `gpt_search` tool call. |
| Vector Search | 1 | Vector search tool calls count as one task. |
| DataForSEO | 1 | Hosted DataForSEO calls also record the provider-side unit charge. |
| xAI Web Search | 1 | Hosted calls use the hosted LLM pool for provider usage. |
| X Search | 1 | Hosted calls use the hosted LLM pool for provider usage. |
| Anthropic Web Search | 1 | Completed hosted calls use the hosted LLM pool for provider usage. |
| Sonar Web Search | 1 | Hosted calls use the hosted LLM pool for provider usage. |
| Perplexity Search | Variable | Each completed invocation is billed independently. Hosted calls use the fixed Search API cost; personal calls cost 1 platform task. |
| Sub-agent | Billed on child run | The child agent creates its own completions and task usage. |
## Structural services
| Service | Task credits | Notes |
| ---------- | ------------------------ | --------------------------------------------------------------------------------------------------------- |
| Workflow | Billed by child services | A workflow step records the nested run result. The nested workflow's own steps carry the task usage. |
| Agent step | Billed on the agent run | A workflow Agent step records the nested agent result. The agent run carries the task usage. |
| Iteration | 0 | Iteration records the fan-out or aggregate result. Steps inside the iteration carry their own task usage. |
| Condition | 0 | Conditions route execution and don't create a billed service call. |
# Analytics
Source: https://docs.fetchhive.com/user-tracking/analytics
Use Fetch Hive user analytics to measure active users, spend, activity trends, and top users
Use the analytics views in Fetch Hive when you want to understand which end users are active, what they cost, and which users drive the most traffic.
## Overview
Fetch Hive exposes user analytics in two places. The dedicated **Users** analytics page focuses on tracked end users, while **Dashboard** analytics includes a broader workspace view with a **Top Users** chart that links into the same user detail page.
These pages work best together. Start in **Users** analytics when you want user-specific trends, then drill into an individual user when you want to inspect that user's usage in detail.
## How do I use Users analytics?
Open **Users** in the main sidebar, then click **Analytics** in the secondary navigation.
Use the date-range control in the header to switch between the preset ranges or choose a custom range.
The page updates all cards and charts for the selected period.
## What metrics and charts are available?
The top row shows four summary cards:
* **Active Users**
* **Total Spend**
* **Avg Cost**
* **Top User Share**
Below that, Fetch Hive shows **User Activity Over Time**. This chart lets you switch between **Cost**, **Requests**, and **Tokens** so you can compare how user activity changes over the selected period.
The lower section includes **Cost Distribution** and **Top Users**.
Use **Cost Distribution** when you want a quick view of how spend is split across your highest-cost users.
Use **Top Users** when you want to rank users by **Cost**, **Requests**, or **Tokens** and move straight into a single user record.
Cost values include both estimated task-credit cost and hosted LLM wallet cost, so user analytics matches the total cost shown on individual logs.
## How do I drill into a user from analytics?
On **Users** analytics, click a user in **Top Users** to open that user's detail page.
The **Top User Share** card also links to the top user for the current period.
You can reach the same destination from **Dashboard** analytics. That page includes its own **Top Users** chart, and clicking a user there opens the same user detail view under **Users**.
## Dashboard analytics vs Users analytics
Use **Users** analytics when your main question is about end-user behavior and spend.
Use **Dashboard** analytics when you want a wider workspace view that also includes service costs, model costs, token usage, and top users in the same report.
Both surfaces are useful, but only the **Users** analytics page is dedicated to tracked user activity.
See also: [Identifying users](./identifying-users) and [Filtering and drilling](./filtering-and-drilling).
# Filtering and drilling
Source: https://docs.fetchhive.com/user-tracking/filtering-and-drilling
Filter tracked users and drill from user-level activity into prompt, workflow, and agent run details
Use the filtering and drill-down tools in Fetch Hive when you want to narrow user activity, switch between resource types, and inspect the runs behind a user's usage.
## Overview
Fetch Hive gives you two levels of filtering in the **Users** section. On the main **Users** page, you narrow the user list. On an individual user page, you refine that user's activity log and open the run details behind each row.
This flow helps you move from a broad user list to a precise run-level investigation without leaving the user-tracking area.
## How do I filter the Users list?
Open **Users** in the main sidebar.
Use the date-range control in the header to switch between the preset ranges or choose a custom range.
Use the search field to filter the table by **User ID**.
If you want to scope the list to a specific credential, use the **API Keys** section in the secondary navigation. Fetch Hive gives you **All Keys** plus one link for each active key.
## How do I switch between prompt, workflow, and agent activity?
Open a user from the **Users** table.
On the user detail page, use **Log Type** in the secondary navigation to switch between **All**, **Prompts**, **Workflows**, and **Agents**.
Fetch Hive reloads the activity table for that selection and resets the contextual filters that no longer apply to the new log type.
## How do I filter a user's activity?
On the user detail page, start with the date-range control in the header if you need to change the period.
Use **Provider**, **Model**, and **API Key** to narrow the activity table across supported runs.
Depending on the selected log type, Fetch Hive also shows contextual filters:
* **Prompt**
* **Source**
* **Agent**
* **Workflow**
Use **Clear filters** to remove the active filters and return to the broader activity view.
## How do I drill into an individual run?
Click any row in the user activity table.
Fetch Hive opens the matching detail sheet for that run type:
* Prompt rows open the prompt completion detail sheet
* Workflow rows open the workflow run detail sheet
* Agent rows open the agent run detail sheet
These sheets let you inspect the run in more detail without leaving the user page.
See also: [Identifying users](./identifying-users) and [Analytics](./analytics).
# Identifying users
Source: https://docs.fetchhive.com/user-tracking/identifying-users
Understand how Fetch Hive surfaces tracked end users as User IDs across the Users pages and run details
Use user tracking when you want Fetch Hive to group usage and cost by the end users behind your API traffic.
## Overview
Fetch Hive centers user tracking around the **Users** section in your workspace. That section shows each tracked end user as a **User ID**, then lets you open that user's analytics and activity history.
When you open a user, Fetch Hive uses that same tracked identifier to load the matching analytics, logs, and activity history you see in the dashboard.
## How do I see tracked users in Fetch Hive?
Open **Users** in the main sidebar.
Fetch Hive shows a table of tracked users for the selected date range.
Each row includes **User ID**, **First Request**, **Last Request**, **Total Requests**, **Total Tokens**, and **Total Cost**.
Use the search field if you want to quickly find a specific identifier.
## How does Fetch Hive show the user identifier in the UI?
On the **Users** page, Fetch Hive labels the tracked identifier as **User ID**.
When you open a user, Fetch Hive uses that value in the user-detail URL and then loads the matching analytics and logs for that same identifier.
You see the same identifier again in places that link back to the user record, including run detail sheets and analytics charts.
That means you can treat **User ID** as the dashboard name for the end-user identifier Fetch Hive tracks across these pages.
## How do I open a specific user from logs or analytics?
You can open a user directly from the **Users** table by clicking a row.
You can also open the same user from **Dashboard** analytics or **Users** analytics by clicking a user inside **Top Users**.
In prompt, workflow, and agent run detail sheets, Fetch Hive also shows a clickable user link when the run includes a tracked user identifier. Selecting that link opens the same user detail page in **Users**.
## User ID across Fetch Hive
Fetch Hive uses the same tracked end-user identifier across the **Users** page, analytics views, logs, and run details.
In the dashboard, that identifier is presented as **User ID**.
If you are documenting or debugging the UI flow, treat **User ID** as the user-facing name for the tracked identifier shown throughout this feature area.
See also: [Analytics](./analytics) and [Filtering and drilling](./filtering-and-drilling).
# Invoke metadata
Source: https://docs.fetchhive.com/user-tracking/invoke-metadata
Pass caller-defined metadata to public invoke endpoints and use it to inspect and filter logs
Use invoke metadata when you want to attach your own audit fields to live prompt, workflow, or agent runs. Metadata is stored with the run, shown in log details, and available as **User metadata** filters in logs.
## Overview
Fetch Hive accepts a `metadata` object on these public invoke endpoints:
* `POST /v1/prompt/invoke`
* `POST /v1/workflow/invoke`
* `POST /v1/agent/invoke`
Use metadata for fields from your application that help you investigate and segment traffic later, such as customer IDs, plan names, regions, experiment names, environments, tenant IDs, or feature flags.
Metadata is not prompt, workflow, or agent input. Prompt variables and workflow start variables belong in `inputs`. Agent messages belong in `message` or `messages`.
## Metadata shape
`metadata` must be a flat object. Keys must be non-empty strings, and values must be strings, numbers, booleans, or `null`.
Nested objects and arrays are rejected before the run starts.
Good metadata examples:
```json theme={null}
{
"customer_id": "cus_123",
"plan": "enterprise",
"region": "us-east-1",
"experiment": "checkout_v2",
"beta_user": true
}
```
Avoid sending sensitive data, secrets, raw user messages, or large payloads in metadata. Keep it small and stable so filters stay useful.
## cURL examples
### Prompt invoke
```bash theme={null}
curl 'https://api.fetchhive.com/v1/prompt/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
"deployment": "support-classifier",
"variant": "default",
"inputs": {
"ticket_text": "The export button is disabled."
},
"metadata": {
"customer_id": "cus_1234",
"plan": "enterprise",
"experiment": "support_triage_v2"
}
}'
```
### Workflow invoke
```bash theme={null}
curl 'https://api.fetchhive.com/v1/workflow/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
"deployment": "research-brief",
"variant": "default",
"inputs": {
"topic": "AI infrastructure trends"
},
"metadata": {
"customer_id": "cus_123",
"region": "us-east-1",
"source": "daily_digest_job"
}
}'
```
### Agent invoke
```bash theme={null}
curl 'https://api.fetchhive.com/v1/agent/invoke' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
"agent": "AGENT_UUID",
"message": "Summarize this account before renewal.",
"metadata": {
"customer_id": "cus_123",
"plan": "enterprise",
"renewal_window_days": 30
}
}'
```
## SDK examples
The official SDKs accept the same `metadata` object on prompt, workflow, and agent invoke helpers.
### Node.js
```typescript theme={null}
import { FetchHive } from "@fetch-hive/sdk";
const client = new FetchHive({ apiKey: process.env.FETCH_HIVE_API_KEY });
const result = await client.invokePrompt({
deployment: "support-classifier",
variant: "default",
inputs: { ticket_text: "The export button is disabled." },
metadata: {
customer_id: "cus_123",
plan: "enterprise",
experiment: "support_triage_v2",
},
});
console.log(result.response);
```
Use the same field with `invokeWorkflow` and `invokeAgent`:
```typescript theme={null}
await client.invokeWorkflow({
deployment: "research-brief",
variant: "default",
inputs: { topic: "AI infrastructure trends" },
metadata: { customer_id: "cus_123", source: "daily_digest_job" },
});
await client.invokeAgent({
agent: "AGENT_UUID",
message: "Summarize this account before renewal.",
metadata: { customer_id: "cus_123", renewal_window_days: 30 },
});
```
### Python
```python theme={null}
from fetch_hive_sdk import FetchHive
client = FetchHive()
result = client.invoke_prompt(
deployment="support-classifier",
variant="default",
inputs={"ticket_text": "The export button is disabled."},
metadata={
"customer_id": "cus_123",
"plan": "enterprise",
"experiment": "support_triage_v2",
},
)
print(result["response"])
```
Use the same argument with `invoke_workflow` and `invoke_agent`:
```python theme={null}
client.invoke_workflow(
deployment="research-brief",
variant="default",
inputs={"topic": "AI infrastructure trends"},
metadata={"customer_id": "cus_123", "source": "daily_digest_job"},
)
client.invoke_agent(
agent="AGENT_UUID",
message="Summarize this account before renewal.",
metadata={"customer_id": "cus_123", "renewal_window_days": 30},
)
```
### Ruby
```ruby theme={null}
require "fetch_hive"
client = FetchHive::Client.new(api_key: ENV.fetch("FETCH_HIVE_API_KEY"))
result = client.invoke_prompt(
deployment: "support-classifier",
variant: "default",
inputs: { ticket_text: "The export button is disabled." },
metadata: {
customer_id: "cus_123",
plan: "enterprise",
experiment: "support_triage_v2"
}
)
puts result["response"]
```
### PHP
```php theme={null}
getenv('FETCH_HIVE_API_KEY')]);
$result = $client->invokePrompt([
'deployment' => 'support-classifier',
'variant' => 'default',
'inputs' => ['ticket_text' => 'The export button is disabled.'],
'metadata' => [
'customer_id' => 'cus_123',
'plan' => 'enterprise',
'experiment' => 'support_triage_v2',
],
]);
echo $result['response'];
```
## Filtering logs by metadata
After runs arrive with metadata, open the matching log page:
* Prompt runs: open the prompt and select **Activity Logs**
* Workflow runs: open **Workflows** and select **Logs**
* Agent runs: open **Agents** and select **Logs**
Use **User metadata** to filter by metadata.
Choose a metadata key to find runs where that key exists. Add a value when you want an exact scalar match, such as `customer_id = cus_123`, `plan = enterprise`, `beta_user = true`, or `renewal_window_days = 30`.
Fetch Hive tracks metadata property names over time from invoke requests so the filter can suggest keys your workspace has actually sent. Older runs without that metadata remain visible normally, but they are excluded when a matching metadata filter is active.
When you open a run detail sheet, metadata appears in the **User metadata** section so you can confirm which caller-defined fields were attached to that run.
## See also
* [Invoke Prompt](../api-reference/prompts/invoke)
* [Invoke Workflow](../api-reference/workflows/invoke)
* [Invoke Agent](../api-reference/agents/invoke)
* [Prompt logs](../prompts/logs)
* [Workflow logs](../workflows/logs)
* [Agent logs](../agents/logs)
# Overview
Source: https://docs.fetchhive.com/user-tracking/overview
Track end-user usage, metadata, analytics, and drill-down activity
This section covers how Fetch Hive groups usage by end user and how you inspect that activity in the dashboard. Use these pages when you want to understand who is generating traffic, what those users cost, and how to drill into the runs behind a specific user.
## What you'll find here
* [Identifying users](./identifying-users) — Understand how Fetch Hive surfaces tracked end users as **User ID** records across the Users pages and run details
* [Invoke metadata](./invoke-metadata) — Pass caller-defined metadata to prompt, workflow, and agent invoke endpoints, then inspect and filter it in logs
* [Analytics](./analytics) — Measure active users, spend, activity trends, and top users in the dedicated user analytics views
* [Filtering and drilling](./filtering-and-drilling) — Narrow the user list, filter a user's activity, and open prompt, workflow, or agent run details
# Account switching
Source: https://docs.fetchhive.com/workspace/account-switching
Switch between Fetch Hive accounts that you belong to
Use **Switch account** when your email belongs to more than one Fetch Hive account. This changes the account context for the dashboard, including billing, workspaces, team members, prompts, workflows, agents, logs, and settings.
## How do I switch accounts?
Open the avatar menu. In the main AI Studio layout, the avatar is at the bottom of the navigation sidebar. On full-page screens such as Plans, Checkout, and Onboarding, it appears in the top-right corner.
Click **Switch account**.
Choose the account you want to use.
Fetch Hive refreshes your dashboard context and opens that account's primary workspace. Owners and admins can see all workspaces in the account. Members see only workspaces where their workspace permission is enabled. If the selected account has no accessible workspace, Fetch Hive returns you to the workspace landing page.
## How do I create my own account?
Open the avatar menu in the top bar.
If you do not already own any account, click **Create new account**.
Fetch Hive creates your first owned account for your existing user, switches you to that account, and opens onboarding so you can name the workspace and finish setup.
If you first joined Fetch Hive through an invitation, accepting the invitation only adds you to the invited account. It does not automatically create a personal account for the same email. Once you own an account, use **Switch account** instead of creating more accounts.
## What changes when I switch accounts?
Account switching changes which account the dashboard sends with authenticated requests. After switching, the current account controls:
* Which workspaces you can open
* Which team members and invitations you can manage
* Which billing plan, limits, and usage apply
* Which account-level assets, integrations, logs, prompts, workflows, and agents are visible
Workspace switching is still separate. First choose the account, then choose a workspace inside that account.
To switch workspaces, open the same avatar menu and open the submenu that shows the current workspace name. Choose another accessible workspace from the list. In AI Studio, Fetch Hive keeps the same workspace-relative area open when possible. On full-page screens, choosing a workspace opens that workspace's dashboard. The submenu also shows your workspace count and the **Create workspace** action.
Selected account mode and staff impersonation mode are separate. Fetch Hive sends only one account-context header on authenticated requests.
Search, logs, integrations, prompts, workflows, agents, templates, and workspace settings follow the same workspace access rules. Owners and admins can search or manage every workspace in the selected account. Members only receive results from workspaces where their permission is enabled, including exact request lookups.
## What if I no longer have access?
If your access to a saved account or workspace is removed or disabled, Fetch Hive clears the saved account choice and returns to your default account the next time your session refreshes.
See also: [Workspace settings](./workspace-settings), [Team members](./team-members), and [Billing](./billing)
# API keys
Source: https://docs.fetchhive.com/workspace/api-keys
Create and manage workspace API keys for calling Fetch Hive deployments across environments
Use **API Keys** when you need credentials for calling Fetch Hive deployments from your own app or service. This page manages workspace API keys, not third-party provider keys for personal model usage.
## Overview
The page separates your **Default API Key** from any additional keys you create for specific environments or services. Additional keys appear in a table where you can search, filter, rotate, revoke, and review last-used activity.
Fetch Hive supports environment-specific keys, so you can keep **Production**, **Staging**, and **Development** access separate.
## How do I create an API key?
Open **Settings** in the sidebar, then click **API Keys**.
If the workspace does not have a default key yet, click **Create Default Key**.
If you want an additional key, click **Add API Key**.
Enter a name and choose the environment:
* **Production**
* **Staging**
* **Development**
Save the key. Fetch Hive then shows **Your New API Key**.
Copy the full key right away. The full value is only shown when the key is first created or rotated.
## How do I rotate or revoke a key?
Find the key you want to change in **Default API Key** or the table of additional keys.
Use **Rotate Key** when you want to replace the current secret with a new one.
Use **Revoke** when you want to disable a key and prevent future use.
Fetch Hive asks you to confirm either action before it proceeds.
## Why can I only copy part of a key?
After the creation or rotation dialog closes, the page keeps the masked key prefix for reference but usually no longer has the full key value available to copy.
That is why you should copy the full secret from **Your New API Key** before you close that dialog.
The masked display is still useful for confirming which key you are looking at and checking its environment, status, and last-used information.
## How is this different from provider credentials?
Workspace API keys authenticate requests to Fetch Hive deployments.
They are different from provider credentials you connect for **Personal** charge type. For that flow, use [Use your own API Key](./llm-providers) and [Integrations](./integrations).
# Billing
Source: https://docs.fetchhive.com/workspace/billing
Review your plan, credits, invoices, and cancellation state from the billing page
Use **Billing** when you need to review your Fetch Hive plan, check credits, confirm upcoming billing dates, or look up past invoices. This page also shows cancellation state and the current account deletion support path.
Only account owners and admins can open Billing. Members do not see this page in Settings.
## Overview
The billing page centers on your active subscription, usage, and invoices. Depending on the state of your account, it can also show trial information, scheduled cancellation or downgrade messaging, and a way to reactivate a pending cancellation.
This page is best for reviewing billing status. It is not the place to manage provider credentials for personal model usage.
## How do I review my plan and credit usage?
Open **Settings** in the sidebar, then click **Billing**.
Review the subscription card to see your current plan, included credits, and the next billing or cancellation date shown on the page. If a promotion code discount applies, the next bill amount reflects the current Stripe billing preview.
Check the credit usage section to understand how much of the current credit allocation you have already used.
In logs and analytics, Fetch Hive shows the platform portion as **Estimated task credit cost**. That estimate is based on your included plan tasks or purchased top-up tasks and is separate from hosted LLM wallet charges.
Metered tools such as search and scrape also show **Service cost** (what the provider charged) and **Service fee (6%)**. Those two figures explain how the task-credit charge was derived. They are not extra charges on top of the tasks, and they are a different 6% from the Hosted LLM Wallet top-up fee below.
If the workspace is in a trial state, the page also shows trial-specific plan details.
## How do Hosted LLM wallet top-ups work?
Choose a wallet-credit pack from **Hosted LLM Wallet**. Checkout shows the
wallet credit, a service fee, and the total before payment. The current default
fee is 6%, with an \$0.80 minimum. The fee is non-refundable and covers provider
accounts, consolidated billing, payment processing, provider funding, and
operational risk. When the minimum applies, checkout says so explicitly.
You can **Edit** the wallet credit in checkout and enter any whole-dollar amount
from **$10** to **$999,999**. Saving refreshes the fee and total from the server. If the
amount differs from the selected pack, checkout switches to a custom purchase
identity; restoring the pack amount restores the original pack name.
The purchased wallet credit never expires. Hosted model, native search, audio,
and image usage is then deducted at the recorded provider cost with no per-call
markup. Historical logs can still show a clearly labelled legacy markup from
usage recorded before pass-through pricing.
## How do I cancel or reactivate a plan?
If your plan can be cancelled from the current state, use **Cancel plan** from the billing page.
Enter a cancellation reason if you want to include one, then confirm the action.
If the page later shows a pending cancellation state, use **Reactivate** to keep the subscription active.
Fetch Hive also surfaces alert banners when a downgrade or cancellation has already been scheduled.
## How do I review invoices?
Scroll to **Invoices** on the billing page.
Use the table to review invoice date, type, status, and amount.
If a row includes a PDF link, open it from the same table when you need the invoice document itself.
## How do I delete my account?
Open the **Delete Account** flow from the billing page if you need to close the account entirely.
You are required to contact [tom@fetchhive.com](mailto:tom@fetchhive.com) for an account deletion follow-up.
If account deletion has already been scheduled, the page can also show that state.
See also: [API keys](./api-keys) and [Security](./security)
# Brand kit
Source: https://docs.fetchhive.com/workspace/brand-kit
Generate and edit your workspace brand profile from a brand URL
Use **Brand Kit** when you want Fetch Hive to store shared brand context for your workspace. This page starts from a public brand URL, then lets you review and edit the generated profile.
## Overview
The brand kit flow starts with **Brand URL**. After you generate the brand kit, the page expands to show editable fields such as **Brand name**, **Brand description**, and **Brand ICP**, plus a competitor list when Fetch Hive finds one.
This is useful when you want your team to reuse the same company context across prompts, workflows, and other workspace features.
## How do I generate a brand kit?
Open **Settings** in the sidebar, then click **Brand Kit**.
Enter the company site in **Brand URL**.
Click **Generate**. If the workspace already has brand data, the button changes to **Re-generate**.
While generation is running, the page shows a generating state and disables edits.
## How do I edit the generated brand profile?
Wait for the generated profile to appear below the URL form.
Review **Brand name**, **Brand description**, and **Brand ICP**.
Edit any field that needs cleanup, then save the change from the inline editor controls.
Use these fields when you want the generated brand profile to match how your team describes the company.
## How do I review competitors?
Scroll to **Competitors** after the brand profile has loaded.
Review the competitor names, descriptions, and outbound links.
If Fetch Hive does not identify any competitors yet, the page shows an empty state instead of a table.
## What happens if generation fails or is incomplete?
The page can show an error state if generation fails.
If that happens, check the **Brand URL**, then run **Re-generate** again.
You can also end up with a partial result. In that case, update the generated fields manually instead of waiting for a perfect automatic result.
See also: [Workspace settings](./workspace-settings)
# Integrations
Source: https://docs.fetchhive.com/workspace/integrations
Connect third-party services to your Fetch Hive workspace with OAuth or API keys
Use **Integrations** when you want Fetch Hive to connect to an external service on behalf of your workspace. Depending on the provider, the connection flow redirects you through OAuth, asks you to paste an API key, or opens a managed service connection flow.
## Overview
The integrations page shows one card per available provider. Each card gives you a **Connect** action and an enabled or disabled state you can change after the integration is set up.
You also use **Integrations** when you choose **Personal** charge type and need to connect provider credentials.
## How do I connect an integration?
Open **Tools** in the sidebar, then click **Integrations**.
Find the provider you want to connect.
Click **Connect**.
If the provider uses OAuth, Fetch Hive redirects you to the provider's sign-in and approval flow.
If the provider uses a direct secret instead, Fetch Hive opens a modal asking for your API key.
If the provider uses a managed flow, follow the provider-specific prompt. For Telegram, Fetch Hive opens the Fetch Hive Bot so you can press **Start** and connect your private Telegram chat.
Complete the OAuth flow, save the API key, or finish the managed connection prompt to finish the connection.
## How do I update a saved integration key?
Open the integration card again and choose **Connect**.
For API-key-based integrations, the same modal opens again so you can replace the saved secret with a new one.
Save the updated key to keep the integration connected with the new credential.
## How do I enable or disable an integration?
Use the switch on the integration card when you want to control whether the connected integration is enabled for the workspace.
Turn it on to enable the integration.
Turn it off to disable it without removing the card itself.
## When should I use integrations?
Use **Integrations** whenever Fetch Hive needs workspace-level access to an external provider.
That includes both general tool connections and provider credentials used by **Personal** charge type flows described in [Use your own API Key](./llm-providers).
## Connecting external apps (Airtable, Linear, Google Calendar, and more)
The Integrations page lists all providers in a uniform grid — AI model providers (OpenAI, Anthropic, etc.) alongside workflow and agent tools (Slack, Airtable, Linear, Google Calendar, and more). There is no separate section.
### Connecting an app
Click **Connect** on any app card. Depending on the provider, Fetch Hive either:
* Shows an API key entry field directly on the card.
* Redirects you through the provider's OAuth flow. After completing the flow, the browser returns to the Integrations page and the card updates to show **Connected** with your account identifier.
* Opens a managed connection flow, such as Telegram's Fetch Hive Bot flow.
### Reconnecting an expired connection
If a connection expires (shown with an amber **Expired — Reconnect** badge), click **Reconnect** to refresh the token.
### Disconnecting an app
Click **Disconnect** to remove the connection. Any workflow steps or agents that relied on this connection will fail until a new connection is established.
See also: [Use your own API Key](./llm-providers) and [API keys](./api-keys)
# Use your own API Key
Source: https://docs.fetchhive.com/workspace/llm-providers
Use Personal charge type in Fetch Hive and connect provider credentials through integrations
Use this page when you want Fetch Hive to run model-backed work against your own provider credentials instead of the hosted default.
## Overview
Fetch Hive exposes two model access modes in the UI:
* **Hosted**
* **Personal**
You choose between them with **Charge Type** controls in the editor surfaces where model-backed work is configured. You can also set a workspace-wide default from **Workspace** with **Default charge type**.
When you choose **Personal**, you should expect to connect the relevant provider credentials through [Integrations](./integrations).
**Personal charge type requires a paid plan** (Growth or above). On the free Developer plan, Fetch Hive stays hosted-only — use your welcome hosted credits or upgrade to unlock Personal.
## How do I set the default charge type?
Open **Settings** in the sidebar, then click **Workspace**.
Find **Default charge type**.
Choose **Hosted** if you want new work to default to Fetch Hive-hosted model access.
Choose **Personal** if you want new work to default toward your own connected provider credentials.
Click **Save** to apply the workspace default.
## How do I use a personal model in prompts, workflows, and agents?
In prompt editors, open **Parameters**, then change **Charge Type** to **Personal**.
In workflow editors, open the relevant **Step settings** for a model-backed step such as **AI Prompt**, then change **Charge Type** to **Personal**.
In agent editors, open **Agent Settings**, then change **Charge Type** to **Personal**.
Fetch Hive supports Personal API keys for OpenAI, Anthropic, xAI, Perplexity, Cohere, and MoonshotAI (Kimi) models. Google Gemini is hosted-only for now while Fetch Hive prepares a proper customer Vertex integration.
After you switch to **Personal**, keep using the same editor surface to choose the model and finish the rest of the configuration.
## How do I connect provider credentials?
Open **Tools** in the sidebar, then click **Integrations**.
Find the provider you want to connect and click **Connect**.
Complete the OAuth flow if the provider uses OAuth.
If the provider uses a direct secret instead, enter the API key in the modal and save it.
Return to your prompt, workflow, or agent after the connection is in place.
## What is the difference between Hosted and Personal?
Use **Hosted** when you want Fetch Hive-hosted model access.
Use **Personal** when you want the provider portion of the usage to be associated with your own connected credentials.
The current cost breakdown UI reflects that difference. When a run uses **Personal**, Fetch Hive labels the provider portion as **Provider Cost (billed to your API key)** and notes **You pay provider separately via your API key**.
When a run uses **Hosted**, Fetch Hive passes the recorded provider cost through
to your LLM Wallet with no per-call markup. The platform portion is shown
separately as **Estimated task credit cost**, based on your included plan tasks
or purchased top-up tasks. Historical runs with nonzero markup are labelled as
legacy pricing in the cost breakdown.
See also: [Workspace settings](./workspace-settings), [Integrations](./integrations), [Prompts](../prompts/overview), [Workflows](../workflows/overview), and [Agents](../agents/overview)
# Media library
Source: https://docs.fetchhive.com/workspace/media-library
Browse, preview, download, and delete shared files from the Fetch Hive media library
Use **Media Library** when you need to review the files available to your Fetch Hive account. This page lets you filter by file type, switch between grid and list views, preview supported files, download them, and delete assets you no longer want to keep.
## Overview
The secondary navigation gives you these file groups:
* **All Files**
* **Images**
* **Documents**
* **Media**
Inside the page, you can search by filename, switch between grid and list layouts, and open a viewer for supported file types such as images, videos, audio files, and PDFs. Document files include PDFs, DOCX files, and spreadsheets.
## How do I browse and filter files?
Open **Media Library** from the sidebar.
Choose **All Files**, **Images**, **Documents**, or **Media** in the secondary navigation to narrow the library by type.
Use the search field when you want to filter the current view by filename.
Use the view toggle in the page header to switch between the grid and list layouts.
## How do I preview or download a file?
Open a file card or list row from the library.
Use the preview action to open the asset viewer.
From the viewer, review the file in place if it is a supported image, video, audio file, or PDF.
Use the download action when you want a local copy of the file.
## How do I delete a file?
Find the file you want to remove.
Choose the delete action from the card or list row.
Confirm the deletion in the dialog.
See also: [Sample inputs and tools](./sample-inputs-and-tools)
Uploading audio in an Agent chat can opt the Asset into managed transcription. Media Library and workflow audio do not transcribe automatically. Agent audio supports MP3 and WAV up to 25 MB and 20 minutes; its cached transcript is reused when that Asset is selected again.
# Notifications
Source: https://docs.fetchhive.com/workspace/notifications
Control discussion mention notifications for your Fetch Hive account
Use **Notifications** when you want to control whether Fetch Hive alerts you about discussion mentions. The current page is focused on discussion notifications, not a broader notification center.
## Overview
This page currently exposes a single setting: **Discussion notifications**. Use it to control whether Fetch Hive notifies you when you are mentioned in discussions.
## How do I manage discussion notifications?
Open **Settings** in the sidebar, then click **Notifications**.
Find **Discussion notifications**.
Turn the switch on if you want mention notifications for discussions.
Turn the switch off if you do not want those notifications.
The change saves from the same page state, so you can confirm the setting immediately after toggling it.
See also: [Team members](./team-members)
# Overview
Source: https://docs.fetchhive.com/workspace/overview
Manage workspace settings, billing, integrations, assets, and team access
This section covers the settings and shared resources that shape how your Fetch Hive workspace works. Use these pages when you need to manage your workspace defaults, team access, developer access, connected services, and reusable assets.
## Switch products
Use the product switcher in the AI Studio header to move between **AI Studio** and **AI Chat**. AI Studio opens the current workspace dashboard. AI Chat opens the dedicated chat app for working with models, agents, and tools in real time. Workspace switching remains in the avatar menu so product choice and workspace context stay separate.
## What you'll find here
* [Workspace settings](./workspace-settings) — Update your workspace name, choose a default charge type, and manage categories
* [Brand kit](./brand-kit) — Generate and edit workspace brand context from a brand URL
* [API keys](./api-keys) — Create, rotate, revoke, and copy workspace API keys for calling Fetch Hive deployments
* [Use your own API Key](./llm-providers) — Use **Personal** charge type and connect provider credentials through **Integrations**
* [Team members](./team-members) — Invite teammates, manage roles, and handle pending or archived access
* [Notifications](./notifications) — Control discussion mention notifications for your account
* [Queuing](./queuing) — Open the **Run Queue**, track queued versus running items, and monitor concurrency usage
* [Billing](./billing) — Review your plan, credits, cancellation state, and invoices
* [Security](./security) — Review active sessions and revoke access from devices you no longer trust
* [Integrations](./integrations) — Connect third-party services with OAuth or API keys
* [Media library](./media-library) — Browse, preview, download, and delete shared files
* [Sample inputs and tools](./sample-inputs-and-tools) — Manage reusable sample inputs and sample tool schemas for editor workflows
# Connect Pinecone
Source: https://docs.fetchhive.com/workspace/pinecone
Connect an API key and select an integrated-embedding index
Connect Pinecone from **Workspace → Integrations** by entering a Pinecone API key. Fetch Hive validates the key by listing indexes and never returns the key in an API response.
Pinecone tools only show ready, dense indexes configured with **Pinecone integrated embedding**. A dense index that stores your own vectors (for example with an `embedding_model` metadata tag) is not enough—Fetch Hive search and write send raw text and rely on Pinecone to embed it. Fetch Hive does not create or reconfigure indexes. See [Pinecone’s indexing overview](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding) for how to create an index with integrated embedding.
Select an existing compatible index and namespace when configuring an agent tool or workflow step. You can also enter a new non-empty namespace; Pinecone creates it on the first write.
Pinecone usage is billed separately by your Pinecone account. Fetch Hive provider-action task limits and credits also apply.
# Queuing
Source: https://docs.fetchhive.com/workspace/queuing
How to open the Run Queue, understand queued versus running items, and track concurrency usage in your workspace
Use **Run Queue** when you need to see which workflow runs are waiting to start, which ones are already running, and how much account concurrency is currently in use.
## Overview
The queue lives in your workspace sidebar, not as a separate page. It gives you a live view of active workflow queue items for your account, including whether each item is still waiting for a slot or already using one.
Hive Agents do not use this **Run Queue** surface for node-level concurrency. Configure Hive Agent node concurrency from **Budget Settings** with **Max Concurrent Nodes**.
## How do I open the queue?
In the left sidebar footer, click **Run Queue**.
If Fetch Hive already has active queue items, the **Run Queue** button can show a count badge.
## How do I read queued versus running items?
**Queued** means the item is waiting for an available concurrency slot.
**Running** means the item has started and is already using one of your available slots.
Only **Queued** items show a **Cancel** control in the sheet. **Running** items do not.
## Why does Fetch Hive queue runs?
Fetch Hive queues workflow runs so your account stays within its concurrency cap. When all available slots are already in use, additional work waits until a slot becomes available instead of starting immediately.
## Concurrency usage
At the top of **Run Queue**, **Concurrency usage** shows how many slots are currently in use out of your total account limit.
For Hive Agents, use **Budget Settings** > **Max Concurrent Nodes** to limit how many executor nodes can run at once inside a Hive Agent run.
See also: [Errors and rate limits](../api-reference/errors-and-rate-limits) and [Hive Agent configuration](../hive-agents/creating-and-configuring).
# Sample inputs and tools
Source: https://docs.fetchhive.com/workspace/sample-inputs-and-tools
Create and manage reusable sample inputs and sample tool schemas for your workspace
Use **Sample Inputs** and **Sample Tools** when you want reusable test data and tool definitions inside Fetch Hive. These pages give your team a shared place to store example payloads and JSON tool schemas that can be reused while building and testing.
## Overview
Both pages use the same general pattern: a searchable table with pagination, a **Columns** menu, and dialogs for creating, editing, and deleting entries.
Use **Sample Inputs** for example request bodies, text payloads, or structured inputs you want to keep around for testing. Use **Sample Tools** for reusable tool schemas edited as JSON.
## How do I manage sample inputs?
Open **Tools** in the sidebar, then click **Sample Inputs**.
Use the search field to filter the table by name or description.
Click **Add Sample Input** to create a new saved input.
Enter the name, add an optional description, and paste the sample value you want to store.
Save the input to add it to the table.
To update or remove an entry later, open it from the table and use the edit or delete flow.
You can also use sample inputs inline while testing prompts and workflows. Prompt variable fields, workflow run start inputs, and workflow start input example fields include actions to load an existing sample input or save the current value as a new sample input.
For workflow **Array** start inputs and examples, saved sample input text must be a valid JSON array before it can be loaded into the field.
## How do I manage sample tools?
Open **Tools** in the sidebar, then click **Sample Tools**.
Use **Add Sample Tool** to create a new tool schema.
Enter the name and optional description, then define the schema in the JSON editor.
Save the tool when the JSON is valid.
If the JSON is invalid, fix the error in the editor before you save.
To update or remove an existing schema, open it from the table and use the edit or delete flow.
## When should I use each?
Use **Sample Inputs** when you need reusable example data to run through prompts, workflows, or agents.
Use **Sample Tools** when you need reusable JSON tool definitions your team can keep consistent across editor work.
See also: [Integrations](./integrations), [Media library](./media-library), [Prompts](../prompts/overview), [Workflows](../workflows/overview), and [Agents](../agents/overview)
# Security
Source: https://docs.fetchhive.com/workspace/security
Review active sessions and revoke access from devices you no longer trust
Use **Security** when you want to review where your Fetch Hive account is signed in. This page helps you inspect active sessions and revoke access from individual devices or every other device at once.
## Overview
The security page shows a sessions table with device and location details, last-seen activity, and a **Current session** badge for the device you are using now. You can search the table, revoke one session, or revoke all other sessions while keeping the current one active.
Revoked sessions stop working across protected Fetch Hive surfaces. Dashboard and JWT-backed API requests validate the session ID and session version before they continue. To keep normal requests fast, successful validations use a short positive cache. The default cache window is 5 minutes and can be changed with `AUTH_SESSION_VALIDATION_CACHE_TTL_SECONDS`, so revoked or suspended JWT-backed access can remain valid until the cached `(sub, sid, sv)` entry expires. Rotating the session version bypasses old cache entries.
## How do I review active sessions?
Open **Settings** in the sidebar, then click **Security**.
Review the sessions table to see where your account is currently signed in.
Use the search field if you want to narrow the table to a specific device or session detail.
Look for the **Current session** badge so you know which row represents the device you are using now.
## How do I revoke one session?
Find the session you want to remove from the table.
Click **Revoke** on that row.
Confirm the action in the dialog to sign that session out.
After a session is revoked, it can no longer use protected auth-service endpoints or continue refreshing access tokens. JWT-backed dashboard/API requests are blocked after the validation-cache window expires. Suspended accounts are blocked the same way.
## How do I revoke all other sessions?
Use **Revoke All Sessions** from the page header when you want to sign out every session except the current one.
Confirm the action in the dialog.
This is the fastest option when you have signed in on multiple devices and no longer trust them.
Your current session remains active so you can keep working.
See also: [Team members](./team-members) and [Billing](./billing)
# Team members
Source: https://docs.fetchhive.com/workspace/team-members
Invite teammates, manage access, and review member status in your workspace
Use **Team Members** when you need to control who can access your Fetch Hive workspace. This page lets you invite new teammates, assign roles, resend invitations, and remove workspace access.
Only account owners and admins can open Team Members. Members do not see this page in Settings, and Fetch Hive also enforces this on the server for invites, resends, cancellations, removals, and permission changes.
## Overview
The **Team Members** page shows your current workspace members in a table with email, role, and status information. You can search the list, use the **Status** filter, and manage access from each row.
The table can show statuses such as **Active**, **Pending**, **Disabled**, and **Archived**.
## How do I invite a team member?
Open **Settings** in the sidebar, then click **Team Members**.
Click **Invite Team Member**.
Enter the teammate's email address.
Choose a role:
* **Member** for standard workspace access
* **Admin** for broader workspace management access
Save the invitation to add the person to the table as **Pending**. The email link opens an invitation page where the teammate signs in with the invited email address and clicks **Accept invitation**. Fetch Hive does not create the account membership or workspace access until they accept.
## How do I manage existing team members?
Use the search field when you want to find a teammate by email.
Use **Status** when you want to narrow the table by the status options shown in the filter menu.
Open a row action when you need to manage a member:
* **Resend invitation** if the invite is still pending
* **Cancel invitation** if you want to revoke a pending invite before it is accepted
* **Remove access** if you want to revoke an accepted member's access to this workspace
Fetch Hive asks you to confirm before cancelling an invitation or removing workspace access.
## What should I know about member status?
The status column tells you whether a teammate is active in the workspace, still waiting on an invitation, disabled, or archived. Only enabled workspace permissions allow a member to open that workspace.
Pending invitations reserve the invitee's role and workspace access, but the account membership and workspace permission are created only after the invitee opens the invitation link, signs in with the invited email address, and accepts. If an existing member accepts a new admin invitation, their account role is upgraded to admin when they accept.
If someone has not accepted their invite yet, use **Resend invitation** from their row instead of creating a second invite for the same person.
See also: [Workspace settings](./workspace-settings) and [Security](./security)
# Workspace settings
Source: https://docs.fetchhive.com/workspace/workspace-settings
Update your workspace name, choose a default charge type, and manage workspace categories
Use workspace settings when you need to control the shared defaults for your Fetch Hive workspace. This page lets you rename the workspace, choose how new work defaults between hosted and personal model usage, and organize assets with categories.
## Overview
The **Workspace** page has two main parts. The form at the top controls **Workspace name** and **Default charge type**. The table below lets you search, add, edit, and delete categories that can be reused across the workspace.
If your team uses prompts, workflows, or agents across different projects, categories give you a simple way to keep those resources organized.
## How do I update my workspace settings?
Open **Settings** in the sidebar, then click **Workspace**.
Edit **Workspace name** if you want to rename the workspace.
Choose a value in **Default charge type**:
* **Hosted** if you want new work to default to Fetch Hive-hosted model access
* **Personal** if you want new work to default toward your own connected provider credentials (available on paid plans — Growth or above)
Click **Save** to apply the changes.
## How do I manage categories?
Stay on **Workspace** and scroll to the categories table.
Use the search field when you want to filter the list by category name or description.
Click **Add category** to create a new category.
Enter a name. You can also add a description if you want to explain how the category should be used.
Save the category to add it to the table.
To update an existing category, open that row and edit its name or description.
To remove a category, delete it from the table and confirm the action.
## What happens when I delete a category?
Fetch Hive asks you to confirm before it deletes a category.
The confirmation warns that prompts and other items using that category can become uncategorized. If you still want to remove it, confirm the delete action from the dialog.
See also: [Use your own API Key](./llm-providers) and [API keys](./api-keys)
# Create an agent
Source: https://docs.fetchhive.com/api-reference/agents/create-an-agent
/openapi.yaml post /v1/public/workspaces/{workspace_id}/agents
Creates a new agent in the requested workspace.
# Delete an agent
Source: https://docs.fetchhive.com/api-reference/agents/delete-an-agent
/openapi.yaml delete /v1/public/workspaces/{workspace_id}/agents/{id}
Destroys the agent record.
# Get an agent
Source: https://docs.fetchhive.com/api-reference/agents/get-an-agent
/openapi.yaml get /v1/public/workspaces/{workspace_id}/agents/{id}
Returns a single active agent belonging to the requested workspace.
# List public workspace agents
Source: https://docs.fetchhive.com/api-reference/agents/list-public-workspace-agents
/openapi.yaml get /v1/public/workspaces/{workspace_id}/agents
Returns standalone agents scoped to the requested public API workspace.
# Update an agent
Source: https://docs.fetchhive.com/api-reference/agents/update-an-agent
/openapi.yaml patch /v1/public/workspaces/{workspace_id}/agents/{id}
Updates an existing agent in the requested workspace.
# List public workspace assets
Source: https://docs.fetchhive.com/api-reference/assets/list-public-workspace-assets
/openapi.yaml get /v1/public/workspaces/{workspace_id}/assets
Returns assets scoped to the workspace attached to the public API key.
# Upload a public workspace asset
Source: https://docs.fetchhive.com/api-reference/assets/upload-a-public-workspace-asset
/openapi.yaml post /v1/public/workspaces/{workspace_id}/assets
Uploads a file and creates a workspace-scoped Asset that can be used as a Hive Agent source.
# List public workspace knowledge base items
Source: https://docs.fetchhive.com/api-reference/knowledge-base-items/list-public-workspace-knowledge-base-items
/openapi.yaml get /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}/items
Returns items for a knowledge base in the requested public API workspace.
# Create a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/create-a-knowledge-base
/openapi.yaml post /v1/public/workspaces/{workspace_id}/knowledge_bases
Creates a new knowledge base in the requested workspace.
# Delete a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/delete-a-knowledge-base
/openapi.yaml delete /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}
Marks a knowledge base for deletion. Cleanup continues asynchronously in the background.
# Get a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/get-a-knowledge-base
/openapi.yaml get /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}
Returns a single active knowledge base belonging to the requested workspace.
# List public workspace knowledge bases
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/list-public-workspace-knowledge-bases
/openapi.yaml get /v1/public/workspaces/{workspace_id}/knowledge_bases
Returns knowledge bases scoped to the requested public API workspace.
# Search a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/search-a-knowledge-base
/openapi.yaml post /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}/search
Performs a vector, full-text, or hybrid search against the knowledge base.
Returns matching chunks above the configured score threshold.
# Update a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/update-a-knowledge-base
/openapi.yaml patch /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}
Updates name, description, or search settings of an existing knowledge base.
# List active models
Source: https://docs.fetchhive.com/api-reference/models/list-active-models
/openapi.yaml get /v1/public/models
Returns all active (non-deprecated) LLM and image-generation models
available in Fetch Hive as a flat array. Excludes embedding-only models.
`provider` identifies the underlying model maker (e.g. `openai`, `anthropic`, `minimaxai`).
`model_type` is `"llm"` for chat/text models and `"image_generation"` for
models that generate images. `is_vision` means a model accepts image input;
`is_image_generation` means a model generates images.
`is_reasoning` is `true` when the model supports reasoning capabilities.
# Get a request
Source: https://docs.fetchhive.com/api-reference/requests/get-a-request
/openapi.yaml get /v1/public/requests/{id}
Returns the status, type, and timing metadata for a run.
Pass the `request_id` returned when you invoked a prompt, workflow, agent, or Hive Agent.
# List public search-service country catalogs
Source: https://docs.fetchhive.com/api-reference/search-services/list-public-search-service-country-catalogs
/openapi.yaml get /v1/public/search_services/countries
Returns the country catalogs used by public search workflow services.
This endpoint is unauthenticated and exposes the value each service expects for location/country configuration.
# Retrieve public search-service country catalog
Source: https://docs.fetchhive.com/api-reference/search-services/retrieve-public-search-service-country-catalog
/openapi.yaml get /v1/public/search_services/{service}/countries
Returns the country catalog for one supported search workflow service.
Use each country object's `value` field when configuring that service.
# Create an agent
Source: https://docs.fetchhive.com/api-reference/agents/create-an-agent
/openapi.yaml post /v1/public/workspaces/{workspace_id}/agents
Creates a new agent in the requested workspace.
# Delete an agent
Source: https://docs.fetchhive.com/api-reference/agents/delete-an-agent
/openapi.yaml delete /v1/public/workspaces/{workspace_id}/agents/{id}
Destroys the agent record.
# Get an agent
Source: https://docs.fetchhive.com/api-reference/agents/get-an-agent
/openapi.yaml get /v1/public/workspaces/{workspace_id}/agents/{id}
Returns a single active agent belonging to the requested workspace.
# List public workspace agents
Source: https://docs.fetchhive.com/api-reference/agents/list-public-workspace-agents
/openapi.yaml get /v1/public/workspaces/{workspace_id}/agents
Returns standalone agents scoped to the requested public API workspace.
# Update an agent
Source: https://docs.fetchhive.com/api-reference/agents/update-an-agent
/openapi.yaml patch /v1/public/workspaces/{workspace_id}/agents/{id}
Updates an existing agent in the requested workspace.
# List public workspace assets
Source: https://docs.fetchhive.com/api-reference/assets/list-public-workspace-assets
/openapi.yaml get /v1/public/workspaces/{workspace_id}/assets
Returns assets scoped to the workspace attached to the public API key.
# Upload a public workspace asset
Source: https://docs.fetchhive.com/api-reference/assets/upload-a-public-workspace-asset
/openapi.yaml post /v1/public/workspaces/{workspace_id}/assets
Uploads a file and creates a workspace-scoped Asset that can be used as a Hive Agent source.
# List public workspace knowledge base items
Source: https://docs.fetchhive.com/api-reference/knowledge-base-items/list-public-workspace-knowledge-base-items
/openapi.yaml get /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}/items
Returns items for a knowledge base in the requested public API workspace.
# Create a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/create-a-knowledge-base
/openapi.yaml post /v1/public/workspaces/{workspace_id}/knowledge_bases
Creates a new knowledge base in the requested workspace.
# Delete a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/delete-a-knowledge-base
/openapi.yaml delete /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}
Marks a knowledge base for deletion. Cleanup continues asynchronously in the background.
# Get a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/get-a-knowledge-base
/openapi.yaml get /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}
Returns a single active knowledge base belonging to the requested workspace.
# List public workspace knowledge bases
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/list-public-workspace-knowledge-bases
/openapi.yaml get /v1/public/workspaces/{workspace_id}/knowledge_bases
Returns knowledge bases scoped to the requested public API workspace.
# Search a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/search-a-knowledge-base
/openapi.yaml post /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}/search
Performs a vector, full-text, or hybrid search against the knowledge base.
Returns matching chunks above the configured score threshold.
# Update a knowledge base
Source: https://docs.fetchhive.com/api-reference/knowledge-bases/update-a-knowledge-base
/openapi.yaml patch /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}
Updates name, description, or search settings of an existing knowledge base.
# List active models
Source: https://docs.fetchhive.com/api-reference/models/list-active-models
/openapi.yaml get /v1/public/models
Returns all active (non-deprecated) LLM and image-generation models
available in Fetch Hive as a flat array. Excludes embedding-only models.
`provider` identifies the underlying model maker (e.g. `openai`, `anthropic`, `minimaxai`).
`model_type` is `"llm"` for chat/text models and `"image_generation"` for
models that generate images. `is_vision` means a model accepts image input;
`is_image_generation` means a model generates images.
`is_reasoning` is `true` when the model supports reasoning capabilities.
# Get a request
Source: https://docs.fetchhive.com/api-reference/requests/get-a-request
/openapi.yaml get /v1/public/requests/{id}
Returns the status, type, and timing metadata for a run.
Pass the `request_id` returned when you invoked a prompt, workflow, agent, or Hive Agent.
# List public search-service country catalogs
Source: https://docs.fetchhive.com/api-reference/search-services/list-public-search-service-country-catalogs
/openapi.yaml get /v1/public/search_services/countries
Returns the country catalogs used by public search workflow services.
This endpoint is unauthenticated and exposes the value each service expects for location/country configuration.
# Retrieve public search-service country catalog
Source: https://docs.fetchhive.com/api-reference/search-services/retrieve-public-search-service-country-catalog
/openapi.yaml get /v1/public/search_services/{service}/countries
Returns the country catalog for one supported search workflow service.
Use each country object's `value` field when configuring that service.