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

# 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