Cost awareness
Every api_request is billed to the user's DataForSEO account. The documentation tools are free. This skill is the gate between the two.
The rule
Do not call api_request until the user has agreed a budget for the task. A budget is a ceiling in USD or a number of calls, stated or confirmed by the user in this conversation. A command or an agent that lists api_request in its allowed tools is not an agreement: the permission only removes the prompt, so the plan below is where the user says yes.
In a non-interactive run with no stated budget, do the free steps (docs, planning, the balance check) and stop before the first paid call.
What is free
docs_list_sections, docs_index, docs_search.
- The GET lookups: locations, languages, model lists, filters.
GET /v3/appendix/user_data: the account balance, rates and spending. DataForSEO states that calling it is not charged.
- DataForSEO's sandbox (
docs_search({url: "appendix/sandbox"})): free, returns dummy data in the real response shape. Useful for checking a body. Whether api_request accepts the sandbox host through its url field has not been verified.
Before the first paid call
- Read the endpoint pages with
docs_search for every path in the plan. Each lists a Pricing link; prices differ by endpoint and some are billed per result row or per 10 SERP results, so do not guess from another endpoint.
- Write the plan as a short table: path, what it answers,
limit or depth, number of calls.
- Show the plan and a cost estimate built from the Pricing pages, with the unknowns named. Ask the user for the ceiling.
- Check the balance with
api_request({method: "GET", path: "/v3/appendix/user_data", noAiMode: true}) and read money.balance. The cropped .ai form is documented for Live and Task GET endpoints only, so this Appendix call goes out unchanged. If the balance cannot cover the plan, say so before spending anything.
- Run the plan in the order that lets an early answer cancel later calls.
- Report the spend. Read the balance again, or send the one call that matters with
noAiMode: true to see cost. The cropped .ai envelope has no cost field.
Keeping the bill small
| Lever |
Why |
Bulk endpoints (keyword_overview up to 700 keywords, bulk_keyword_difficulty and the Backlinks bulk_* endpoints up to 1000 targets, ai_keyword_data/keywords_search_volume up to 1000) |
One call instead of a loop |
An explicit limit or depth |
In .ai mode the default is 10; 1000 rows when 50 will do costs more |
filters and order_by in the request |
Pay for the rows you need, not the rows you discard |
_lite variants of the LLM Mentions endpoints |
Cheaper answers when the full breakdown is not needed |
SERP depth in steps of 10 |
The SERP is billed per 10 results |
max_crawl_pages kept small on OnPage crawls |
It multiplies the cost of a crawl |
| Keep every answer in the conversation |
Never fetch the same data twice |
Test a body in the sandbox or with docs_search first |
A failed paid request is a wasted request |
When a call fails
Stop and read status_code and status_message against docs_search({url: "appendix/errors"}). Fix the body, then retry once. Do not loop on a failing call.
1---2name: cost-awareness3description: Use as the budget gate before the first paid DataForSEO api_request of a task, after the task skill has chosen its endpoints, and for any question about DataForSEO pricing - what a call costs, which calls are free, how to estimate or cap spend, how to check the account balance, and how to keep a bill small with bulk endpoints and explicit limit or depth.4metadata:5 source: https://skillmd.com/skills/agents-store/cost-awareness6---78# Cost awareness910Every `api_request` is billed to the user's DataForSEO account. The documentation tools are free. This skill is the gate between the two.1112## The rule1314**Do not call `api_request` until the user has agreed a budget for the task.** A budget is a ceiling in USD or a number of calls, stated or confirmed by the user in this conversation. A command or an agent that lists `api_request` in its allowed tools is not an agreement: the permission only removes the prompt, so the plan below is where the user says yes.1516In a non-interactive run with no stated budget, do the free steps (docs, planning, the balance check) and stop before the first paid call.1718## What is free1920- `docs_list_sections`, `docs_index`, `docs_search`.21- The GET lookups: locations, languages, model lists, filters.22- `GET /v3/appendix/user_data`: the account balance, rates and spending. DataForSEO states that calling it is not charged.23- DataForSEO's sandbox (`docs_search({url: "appendix/sandbox"})`): free, returns dummy data in the real response shape. Useful for checking a body. Whether `api_request` accepts the sandbox host through its `url` field has not been verified.2425## Before the first paid call26271. **Read the endpoint pages** with `docs_search` for every path in the plan. Each lists a Pricing link; prices differ by endpoint and some are billed per result row or per 10 SERP results, so do not guess from another endpoint.282. **Write the plan** as a short table: path, what it answers, `limit` or `depth`, number of calls.293. **Show the plan and a cost estimate** built from the Pricing pages, with the unknowns named. Ask the user for the ceiling.304. **Check the balance** with `api_request({method: "GET", path: "/v3/appendix/user_data", noAiMode: true})` and read `money.balance`. The cropped `.ai` form is documented for Live and Task GET endpoints only, so this Appendix call goes out unchanged. If the balance cannot cover the plan, say so before spending anything.315. **Run the plan** in the order that lets an early answer cancel later calls.326. **Report the spend.** Read the balance again, or send the one call that matters with `noAiMode: true` to see `cost`. The cropped `.ai` envelope has no `cost` field.3334## Keeping the bill small3536| Lever | Why |37|---|---|38| Bulk endpoints (`keyword_overview` up to 700 keywords, `bulk_keyword_difficulty` and the Backlinks `bulk_*` endpoints up to 1000 targets, `ai_keyword_data/keywords_search_volume` up to 1000) | One call instead of a loop |39| An explicit `limit` or `depth` | In `.ai` mode the default is 10; 1000 rows when 50 will do costs more |40| `filters` and `order_by` in the request | Pay for the rows you need, not the rows you discard |41| `_lite` variants of the LLM Mentions endpoints | Cheaper answers when the full breakdown is not needed |42| SERP `depth` in steps of 10 | The SERP is billed per 10 results |43| `max_crawl_pages` kept small on OnPage crawls | It multiplies the cost of a crawl |44| Keep every answer in the conversation | Never fetch the same data twice |45| Test a body in the sandbox or with `docs_search` first | A failed paid request is a wasted request |4647## When a call fails4849Stop and read `status_code` and `status_message` against `docs_search({url: "appendix/errors"})`. Fix the body, then retry once. Do not loop on a failing call.