Run a paid data task
run_capabilityRun one paid data capability (company data, people and contact data and the like) through Ahel's provider execution: it is quoted, the exact price is reserved from the workspace balance, and the run starts. Give id, a task id or tool id from capability_search: it runs only through the v2 capability Ahel's task map binds to it, and an item that is not ready is refused with its exact reason before anything is quoted. It then waits up to wait_seconds (default 20, at most 50; 0 answers at once): when the run finishes in that time, this same answer has its state, exact cost and rows, and generated images and audio as links; otherwise it answers the execution id, and capability_run_status reads the run. An answer with rows also has results_page and csv_url: give the person those links instead of writing the rows out again. Data collection only: a capability that writes or has a side effect is refused. Ahel picks the provider unless endpoint_ids pins one; exclude_endpoint_ids leaves providers out. Give max_cost_usd to hold the price: a run that would cost more is refused with nothing run or charged. Give idempotency_key so a retry after a lost answer is safe: the same key answers the same run, with no new charge. Give tag (such as a customer name) to see usage and cost by tag in Activity. A list: for people.email.find or companies.register.search or companies.emails.from_website, give rows (objects) or rows_text (paste up to 100 rows as text) instead of arguments: without confirm it answers the list's quote and runs nothing; with confirm true it runs every row once and answers the receipt (found, not found, failed, the exact total, the rows and a CSV link) and its run_id; run_id continues a run whose rows were still going. NOT for: the team's own tools, which is my_tools.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "run_capability"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | A task id or tool id from capability_search or capability_inspect. | |
| tag | No | Optional: a label for this run, such as the customer or project it is for: 1 to 64 lowercase letters, digits, dots, dashes or underscores. Activity shows runs and cost by tag. It stays in Ahel and is never sent to a provider. | |
| rows | No | A list for people.email.find or companies.register.search or companies.emails.from_website: 1 to 100 rows, each run once as its own run with its own exact cost. One object per row, such as {"name": "Patrick Collison", "domain": "stripe.com"} or {"name": "Wise", "country": "GB"}. | |
| run_id | No | With id: the run_id a list's receipt answered, to read its rows still running and start the rest. Rows already run are never run twice. | |
| confirm | No | With rows or rows_text: true runs the list once the person agrees to its quote. Left out, the answer is the quote and nothing runs. The same list sent again the same UTC day answers the first run's receipt and neither runs nor charges again; a new idempotency_key runs it again. | |
| arguments | No | The capability's inputs, by name. Required unless rows, rows_text or run_id is given; with a list, {"verify": true} checks every found email. | |
| max_items | No | Most rows to collect, 1-100. Default 10. | |
| rows_text | No | A list for people.email.find or companies.register.search or companies.emails.from_website: 1 to 100 rows, each run once as its own run with its own exact cost. Instead of rows: paste up to 100 rows as text, one per line ("Patrick Collison, stripe.com"; "Wise, GB") or a CSV with a header row (name, domain, linkedin_url; name, country). | |
| endpoint_ids | No | Optional: run only on these providers, by the endpoint ids capability_inspect lists. Leave it out to let Ahel pick (the default). | |
| max_cost_usd | No | Optional: the most this run may cost, in USD, such as "0.05". capability_inspect's next names the quoted maximum. Ahel uses only providers that fit under it, and when none does the run is refused with nothing run or charged. One run only; a list has its own quote and confirm. | |
| wait_seconds | No | Optional: how long to wait for the run to finish and answer its rows here, 0-50 seconds. Default 20; 0 answers the execution id at once. A list waits up to 45 s. | |
| capability_id | No | Instead of id: a v2 capability id from capability_run_status (no execution_id). | |
| idempotency_key | No | Optional: your own key for this run, 8 to 200 letters, digits, dots, underscores, colons or hyphens. Sending the same call again with the same key answers the same run with no new charge; the same key with different inputs is refused. | |
| timeout_seconds | No | Longest the run may take, 1-180 seconds. Default: the provider's own (60, more for slow sources). | |
| exclude_endpoint_ids | No | Optional: never use these providers, by the endpoint ids capability_inspect lists. Ahel picks among the rest. |