> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/integrations/bland. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt

# Bland

Give a Bland phone agent live web search. A webhook tool sends the caller's question to SpecStream, and a few seconds later the agent has the answer, the page it was read on, and the time it was read.

[SpecStream for BlandAgent frameworks & builders](https://specstream.ai/integrations/bland.md)

## What you need

-   A Bland agent you can edit in the agent builder, and the owner, admin or operator role to add a secret.
-   A SpecStream account. New accounts start with $10 of credit, no card. [Create one](https://specstream.ai/signup?utm_source=bland).

1.  1

    ## 1. Store your SpecStream key as a secret

    Copy your key from the [Search API screen](https://specstream.ai/workspace/search?utm_source=bland&utm_medium=howto) of your SpecStream workspace, or create one under **Agents & API**, **API keys**, **Create API key**, with a spending limit above zero.

    In Bland, set the sidebar selector to **All agents**, open **Tools**, and on the **Secrets** tab click **Add Secret**. Name it `specstream_api_key` and paste the key as a **Static** secret.

2.  2

    ## 2. Create a webhook tool

    Open your agent, go to **Tools**, click **Create tool**, and choose **Webhook**.

    **Name**: `Search live web`. **Description**: `Answer a question about something current or specific that you do not know for certain: opening hours, a price, a date, who holds a role at a company, a recent event, or a fact on a named website.` **Agent speech**: `One moment, let me check that.`

3.  3

    ## 3. Point it at the Search API

    Set the method to **POST** and the URL to `https://api.specstream.ai/v1/web-search`. On the **Authorization** tab, choose **Bearer Token** and pick `specstream_api_key`. On the **Headers** tab, add `Content-Type` with the value `application/json`. On the **Body** tab, enter:

    Body

    ```json
    {
      "q": "{{q}}"
    }
    ```

4.  4

    ## 4. Let the agent fill in the question

    Under **Detected variables**, click **Add input variable** next to `q`. Set its type to string, mark it required, and give it this instruction: `The caller's question as one short, complete question, with names and places spelled out.`

5.  5

    ## 5. Declare the answer fields

    Keep `ok` and `message` checked under **Output fields**, then save the tool and open it again: on a POST tool the response rows are named `rest_api_post_*` only after the first save. Add these rows, each with a name and a JSONPath:

    `answer`: `$.data.rest_api_post_data.data.answer.value`. `answer_page`: `$.data.rest_api_post_data.data.answer.page`. `top_result`: `$.data.rest_api_post_data.data.sources[0].snippet`.

    Set **Timeout** to `15000`. Checking at least one output field is what makes the tool wait for the answer.

6.  6

    ## 6. Test it

    Run the tool with a sample question, such as today's opening hours of a shop in your city. The response shows `ok` as true and the answer in `answer`. A `401` means the secret holds the wrong key; a `403` names the spending limit to raise.

7.  7

    ## 7. Tag the tool into the prompt

    Building the tool does not give it to the agent. In the agent's **Prompt**, type `@`, pick **Search live web**, and add how to use the answer. Check that the tool now shows under **Tool references**:

    Agent prompt

    ```text
    When the caller asks about something that can change, use @Search live web. If {{ok}} is true and {{answer}} is filled, say it in one or two sentences, and if the caller asks where it comes from, name the website in {{answer_page}}. If {{answer}} is empty, say you could not confirm it and offer to follow up. Do not read out web addresses.
    ```

## What comes back

Bland puts SpecStream's reply in `data.rest_api_post_data`. The reply is JSON with one key, `data`. For a question with one answer, `data.kind` is `fact`, and `data.answer` holds the `value` as the page prints it, the `page` it was read from, and `seen_at`, the time it was read. `data.sources` lists the search results read, each with its `url`, `title`, `site` and `snippet`.

When no page prints a value that answers the question, `data.answer` is `null`, so `answer` stays empty and the agent says so in place of guessing.

## Inside a pathway

Tools attach per prompt, and they do not follow the agent into a pathway. If the step that needs live answers lives in a pathway, tag **Search live web** in that pathway's prompt too.

Tagging gives the agent its own copy of the tool. To change the tool later, open it from the agent's **Tool references** row, so the agent's copy changes too.

## On the legacy Custom Tools API

Bland now calls Custom Tools legacy and builds new tools in the agent builder. If your calls still send a `tools` array with the call request, the same search fits that form. The `{{input}}` variable comes from `input_schema`, and `response` maps the reply into variables you use in the prompt as `{{answer}}` and `{{answer_page}}`:

## When the caller asks for a list

For a request for many results, `data.kind` is `list`, and `data.rows` holds the first rows, each with its `name`, its `page` and the facts the request asks for. The full list is a Deep Search run: `data.handoff` gives its estimated size and the call that starts it. A Deep Search run is quoted first and starts only after you approve its maximum, so it runs after the call, in your workspace or through the API, with the source URL and read time on every value.

## Cost

Each tool call is one search at $5 per 1,000 searches of up to 10 results, taken from your balance with no quote and no approval. A search that returns no results costs nothing, and the reply's `price_usd` is what the call cost. The key's spending limit caps what the agent can spend, and Bland bills its own minutes separately. Search runs on the Search API, the most accurate web search API in the world on [our published benchmarks](https://specstream.ai/benchmarks.md). See [balance, quotes, and billing](https://specstream.ai/docs/billing.md).

## Disconnect

Remove **Search live web** from the agent's prompt and delete it under **Tools**, then revoke the key in **Agents & API** and delete the `specstream_api_key` secret in Bland. Questions go to [support@specstream.ai](mailto:support@specstream.ai).

## More

[SpecStream for Bland](https://specstream.ai/integrations/bland.md) covers what it does in Bland on one page. Every other tool has its guide in [Connect your tools](https://specstream.ai/docs/integrations.md). You see the most a request can cost before it starts, and the matches are paid from your balance. [Billing](https://specstream.ai/docs/billing.md) has the details. For help, email [support@specstream.ai](mailto:support@specstream.ai).