DifyComing soon
Give a Dify agent or workflow live web data. The SpecStream plugin adds a tool that finds rows from a request in plain words, within a maximum price you set, and a tool that reads them back later. Every row carries the page it was read from and when.
SpecStream for DifyAgent frameworks & builders
Until the Marketplace page works, the MCP server at https://api.specstream.ai/mcp and the REST API give any app that can call them the same data. Pass your key in an Authorization: Bearer header.
What you need
- Dify 1.0.0 or later.
- A SpecStream account, free to open. The first $10 of work needs no card and lasts 30 days.
- A SpecStream API key.
- 1
1. Install the plugin
In Dify, open the Marketplace, search for SpecStream, and install the plugin. It connects only to
https://api.specstream.ai, over HTTPS. - 2
2. Create an API key
Go to Agents & API in SpecStream, open the API keys tab and use Create API key. Label it for Dify. Find a List starts paid work, so keep Authorize paid work on. Then click Set a total limit and enter the most your agents and workflows may spend with this key.
Keys expire after 30 days unless you change Expires after, days. When the plugin's authorization starts failing, an expired key is the first thing to look for. Copy the key from the next screen, because SpecStream shows it once. A key without Authorize paid work can still read lists with Get List Results.
- 3
3. Authorize the plugin
Open the SpecStream plugin's authorization in Dify, paste the key into SpecStream API key and save. Dify asks SpecStream about the key before it saves, and shows an error if SpecStream doesn't accept it.
- 4
4. Add Find a List
Add Find a List to an agent or a workflow. The model fills in What to find, the request in plain words, and Number of results. You fill in Maximum price (USD) and Wait for results (seconds) when you add the tool, and the model never sees them.
SpecStream prices the request before anything starts. If the price is above your maximum, nothing starts and nothing is charged. Otherwise the request starts, the tool waits up to the seconds you set, and it returns the rows found so far.
- 5
5. Read the rest with Get List Results
Get List Results takes a List ID, the
list_idthat Find a List returned. It starts withfnd_. The tool returns the list's status and its rows, and it costs nothing.Use it when Find a List returned before the list finished, or whenever you want the current rows again.
What the tools return
The tools return JSON with list_id, status, number_of_rows, list_link, and rows. status is one of running, completed, partial, failed, canceled, or expired. number_of_rows counts every match, while rows holds up to 100 per call, so open list_link to see a longer list in your workspace.
Each item in rows has the request's columns, keyed by their names, plus these fields. A column named like one of them gets "(column)" added to its name:
| Field | What it holds |
|---|---|
id | The list ID and the row's own ID, joined with a colon. |
list_id | The list the row belongs to. |
list_link | Opens the list in your workspace. |
position | The row's place in the list. |
source_url | The page the row's first value came from. |
checked_at | When that page was read. |
Find a List settings
The model fills in What to find and Number of results. The other settings are yours.
| Setting | Set by | What it does |
|---|---|---|
| What to find | The model | The request in plain words, with the place and the details to bring back. |
| Number of results | The model | How many matching rows to look for, from 1 to 1,000. The default is 25. |
| Maximum price (USD) | You | The most one request may cost. Above it, nothing starts. |
| Wait for results (seconds) | You | How long to wait for rows before returning, from 0 to 150. The default is 90. The list keeps running afterward. |
Price limit and retries
- When the most a request could cost is above Maximum price (USD), nothing starts and nothing is charged. The tool says what it would have cost.
- You pay for rows that match. If a request finds nothing, you pay nothing.
- A retry doesn't pay twice. The same request, count, and maximum, sent again within the hour, returns the list that already started.
If something doesn't work
| What you see | What to do |
|---|---|
| Invalid SpecStream API key. | Create a new key and paste it into the authorization again. An expired or deleted key gives this message. |
| Could not verify the API key with SpecStream. Try again in a moment. | SpecStream answered with an error that isn't a rejected key. Save the authorization again in a moment. |
| Could not reach SpecStream. Try again in a moment. | Dify couldn't connect to api.specstream.ai. Try again, and write to [email protected] if it keeps happening. |
| SpecStream needs a clearer request before it can price it. | Add the place or more detail to What to find. The message quotes how SpecStream read the request. |
| This list can cost up to $X, above the maximum of $Y | Raise Maximum price (USD) or lower Number of results. Nothing started and nothing was charged. |
status is running when the tool returns | The wait ended before the list did. Run Get List Results with the list_id later. |
Pass the list ID from Find a List. It starts with fnd_. | Give Get List Results the list_id that Find a List returned. |
What the plugin sends
The plugin sends the text of each request, the number of results, and your maximum price to api.specstream.ai, authenticated with your key, and reads back the list's status and rows. It stores nothing, logs nothing, and sends nothing to any other service. SpecStream keeps your lists in your account as the privacy policy describes.
Cost
The plugin is free. SpecStream charges your balance for matching rows, from 10 cents each, and a request that finds nothing costs nothing. Get List Results is free. Every rate is on pricing, and the billing page explains quotes and charges.
Remove
Uninstall the plugin in Dify. Deleting the key under Agents & API stops it working in every tool. Anything those lists found remains in your workspace.
Source: GitHub (opens in a new tab). More ways to connect SpecStream are in Connect your tools, and [email protected] answers questions about this plugin.
More
SpecStream for Dify covers what it does in Dify on one page. Every other tool has its guide in Connect your tools. You see the most a request can cost before it starts, and only the matches come out of your balance. Billing has the details. For help, email [email protected].