Dataforseo api

DataForSEO API

Use the dfs command to access DataForSEO directly. It accepts any relative v3 API path and refuses potentially paid requests unless --execute is supplied.

Spending rule

Assume DataForSEO data endpoints are paid unless current official documentation explicitly says otherwise.

1. Prefer supplied data or free first-party sources when they can answer the question reliably.
2. Before a paid call, state the endpoint, purpose, scope, and expected cost or documented cost basis.
3. Get explicit approval from the user or operator before adding --execute.
4. Treat approval as limited to the described call or bounded batch, not as standing authorization.
5. For unattended automation, require an explicit per-run budget and permitted scope.
6. dfs account uses the known free account endpoint and may be used to check authentication, balance, and limits.

The CLI gate prevents accidental execution. It does not enforce a monetary limit.

Workflow

1. Confirm paid SEO data is necessary

Use DataForSEO when the task needs evidence such as:

• search volume, difficulty, CPC, intent, or keyword trends;
• live or location-specific SERPs;
• ranked keywords, domain intersections, or competitor visibility;
• backlinks and referring domains;
• on-page crawl data;
• local business, merchant, app, content-analysis, or AI-visibility data.

Do not use a paid endpoint for ordinary web facts or when a free authoritative source is sufficient.

2. Select the endpoint from current official documentation

DataForSEO changes over time. Inspect the official v3 documentation before constructing an unfamiliar request:

• API index: https://docs.dataforseo.com/v3/
• Authentication: https://docs.dataforseo.com/v3/auth/
• Account data: https://docs.dataforseo.com/v3/appendix/user_data/

Do not guess endpoint paths, payload fields, pricing, location codes, or task semantics from memory.

Prefer the smallest sufficient request:

• narrow the location and language;
• use the minimum useful result limit or depth;
• avoid overlapping endpoints;
• batch only when the user approved the whole batch and documentation shows it is appropriate;
• prefer task or standard endpoints over live endpoints when latency is unimportant and current pricing makes them cheaper.

3. Check account state

Run the sanitized account check when authentication, balance, limits, or recent spend matters:

dfs account

It excludes the account login and reports compact balance, request-limit, spending-limit, and recent-spend fields.

4. Preflight without spending

Store non-secret payloads in a temporary file or the current project's ignored artifact directory:

dfs request POST /v3/<official-endpoint> --data-file /tmp/dataforseo-request.json

Without --execute, the command must fail closed with exit code 2. This refusal occurs before credentials are loaded and before any network request.

Before seeking approval, show:

• request method and endpoint;
• targets or queries, market, language, depth or limit, and item count;
• live versus task or standard method;
• expected price, documented cost basis, or clearly labelled uncertainty;
• maximum bounded calls and spend where possible.

5. Execute only after approval

dfs request POST /v3/<official-endpoint> \
  --data-file /tmp/dataforseo-request.json \
  --execute

The response JSON is written to standard output. Provider-reported actual cost is written to standard error.

After execution:

1. Verify a successful exit status.
2. Check the expected result collection; do not treat an unexpected empty result as success.
3. Preserve raw JSON when auditability or reuse matters.
4. Separate provider data from interpretation.
5. Report actual DataForSEO cost.
6. Remove temporary payloads and results when they contain sensitive query context and are no longer needed.

Task-based endpoints

Some products use task_post, tasks_ready, and task_get instead of one live call.

• Treat task_post as potentially billable and require approval.
• Persist every returned task ID before polling.
• Poll only the documented readiness or result endpoint.
• Bound polling attempts and timeout visibly.
• Never blindly retry a paid task_post after a timeout or ambiguous network failure. First inspect ready or task lists or retrieve the retained task ID to avoid duplicate spend.
• Report partial, failed, and billed-but-failed tasks explicitly.

Command reference

dfs account

dfs request GET  /v3/... [--execute]
dfs request POST /v3/... --data '<json>' --execute
dfs request POST /v3/... --data-file payload.json --execute
dfs request POST /v3/... --data-file - --execute

Only relative /v3/... paths are accepted, and HTTP redirects are refused, so API credentials cannot leave the DataForSEO API origin. Except for the account endpoint, GET requests also require --execute because some DataForSEO GET endpoints may be billable.

Failure handling

• Exit code 2 indicates local safety refusal, invalid input, credential failure, HTTP failure, or a DataForSEO API or task error.
• Do not hide empty responses, task failures, rate limits, insufficient balance, or schema failures.
• Do not fabricate SEO metrics when a call fails.
• Do not retry paid POST requests automatically.
• If current pricing cannot be determined, state the uncertainty and ask whether to proceed.

Verification

command -v dfs
dfs --help
dfs account

When working from a source checkout, also run:

python3 -m unittest discover -s tests -v

Do not claim the client is healthy without passing tests and a successful account check. The account check uses the documented free endpoint and makes a real authenticated network request.