Web scraping
Your Scraping API plan, its credits and its API key.
/api/v1/scraping/products List products
GET /api/v1/scraping/productsThe plans on sale. A subscription product grants plan credits each cycle for a price per term, renewed while it is paid; a payg product adds a pack of credits that never expire. Prices carry no currency; POST /quote and POST /plans/{plan}/quote answer the exact total.
Requires the api.scraping.read scope.
limitinteger50.offsetinteger0.curl https://api.datafuel.ai/api/v1/scraping/products \ --header 'Authorization: Bearer df_live_your_key_here'
OK.
{ "results": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "subscription", "name": "string", "tagline": "string", "description": "string", "prices": [ { "period_days": 0, "price": 0, "allowance": { "credits": null, "cycle_days": null, "concurrency": null }, "credits_per_term": 0, "top_up_per_thousand": 0 } ], "pack": { "credits": 0, "concurrency": 0 }, "price": 0 } ], "count": 0, "limit": 0, "offset": 0 }
The request is malformed: message maps each invalid field to its problem, or is a sentence when the body cannot be read at all.
{ "error": "string", "message": "string", "meta": {} }
The API key is missing, invalid, expired or revoked.
{ "error": "string", "message": "string", "meta": {} }
The key lacks the scope named in meta.required (or the level in meta.required_level), is used from an IP it does not allow, or the account is suspended.
{ "error": "string", "message": "string", "meta": {} }
Too many requests for this key; retry after the Retry-After seconds.
{ "error": "string", "message": "string", "meta": {} }
Something failed on our side and was logged; read the resource again before retrying a change.
{ "error": "string", "message": "string", "meta": {} }
/api/v1/scraping/products/{product} Get a product
GET /api/v1/scraping/products/{product}The product with, for a subscription, each term's price, allowance and what extra credits cost on it, or, for payg, its pack and price. A top-up on a term costs top_up_per_thousand per 1,000 credits, the term's own price per credit.
Requires the api.scraping.read scope.
product REQUIREDstringcurl https://api.datafuel.ai/api/v1/scraping/products/{product} \ --header 'Authorization: Bearer df_live_your_key_here'
OK.
{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "subscription", "name": "string", "tagline": "string", "description": "string", "prices": [ { "period_days": 0, "price": 0, "allowance": { "credits": 0, "cycle_days": 0, "concurrency": 0 }, "credits_per_term": 0, "top_up_per_thousand": 0 } ], "pack": { "credits": 0, "concurrency": 0 }, "price": 0 }
The API key is missing, invalid, expired or revoked.
{ "error": "string", "message": "string", "meta": {} }
The key lacks the scope named in meta.required (or the level in meta.required_level), is used from an IP it does not allow, or the account is suspended.
{ "error": "string", "message": "string", "meta": {} }
No such resource, or it does not belong to the key's owner.
{ "error": "string", "message": "string", "meta": {} }
Too many requests for this key; retry after the Retry-After seconds.
{ "error": "string", "message": "string", "meta": {} }
Something failed on our side and was logged; read the resource again before retrying a change.
{ "error": "string", "message": "string", "meta": {} }
/api/v1/scraping/plans List your plans
GET /api/v1/scraping/plansYour account holds one scraping plan at most, so the list has 0 or 1 entries. It stays empty until you subscribe or activate the Scraping API in the dashboard.
Requires the api.scraping.read scope.
limitinteger50.offsetinteger0.curl https://api.datafuel.ai/api/v1/scraping/plans \ --header 'Authorization: Bearer df_live_your_key_here'
OK.
{ "results": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "provisioning", "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "period_days": 0, "expires_at": "2026-01-01T00:00:00Z", "cycle": { "credits": 0, "used": 0, "started_at": "2026-01-01T00:00:00Z", "resets_at": "2026-01-01T00:00:00Z" }, "credits": { "balance": 0, "plan": 0, "payg": 0, "used_24h": 0, "stale": false }, "concurrency": { "current": 0, "limit": 0 }, "created_at": "2026-01-01T00:00:00Z" } ], "count": 0, "limit": 0, "offset": 0 }
The request is malformed: message maps each invalid field to its problem, or is a sentence when the body cannot be read at all.
{ "error": "string", "message": "string", "meta": {} }
The API key is missing, invalid, expired or revoked.
{ "error": "string", "message": "string", "meta": {} }
The key lacks the scope named in meta.required (or the level in meta.required_level), is used from an IP it does not allow, or the account is suspended.
{ "error": "string", "message": "string", "meta": {} }
Too many requests for this key; retry after the Retry-After seconds.
{ "error": "string", "message": "string", "meta": {} }
Something failed on our side and was logged; read the resource again before retrying a change.
{ "error": "string", "message": "string", "meta": {} }
/api/v1/scraping/plans/{plan} Get a plan
GET /api/v1/scraping/plans/{plan}The plan with its credit balance, concurrency, current term and credit cycle, and a masked preview of its API key. The key itself is only answered by GET /plans/{plan}/credentials.
Requires the api.scraping.read scope.
plan REQUIREDstringcurl https://api.datafuel.ai/api/v1/scraping/plans/{plan} \ --header 'Authorization: Bearer df_live_your_key_here'
OK.
{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "provisioning", "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "period_days": 0, "expires_at": "2026-01-01T00:00:00Z", "cycle": { "credits": 0, "used": 0, "started_at": "2026-01-01T00:00:00Z", "resets_at": "2026-01-01T00:00:00Z" }, "credits": { "balance": 0, "plan": 0, "payg": 0, "used_24h": 0, "stale": false }, "concurrency": { "current": 0, "limit": 0 }, "created_at": "2026-01-01T00:00:00Z", "api_key_preview": "string" }
The API key is missing, invalid, expired or revoked.
{ "error": "string", "message": "string", "meta": {} }
The key lacks the scope named in meta.required (or the level in meta.required_level), is used from an IP it does not allow, or the account is suspended.
{ "error": "string", "message": "string", "meta": {} }
No such resource, or it does not belong to the key's owner.
{ "error": "string", "message": "string", "meta": {} }
Too many requests for this key; retry after the Retry-After seconds.
{ "error": "string", "message": "string", "meta": {} }
Something failed on our side and was logged; read the resource again before retrying a change.
{ "error": "string", "message": "string", "meta": {} }
/api/v1/scraping/plans/{plan}/credentials Get the credentials
GET /api/v1/scraping/plans/{plan}/credentialsThe plan's Datafuel Scraping API key, sent as the X-API-Key header to the Scraping API. It is a secret, so reading it needs the manage level, and it is answered with Cache-Control: no-store. 409 plan_suspended while the plan is suspended, plan_provisioning while it is still being set up.
Requires the api.scraping.manage scope. Every call is recorded in the account's audit log.
plan REQUIREDstringcurl https://api.datafuel.ai/api/v1/scraping/plans/{plan}/credentials \ --header 'Authorization: Bearer df_live_your_key_here'
OK.
{ "api_key": "string", "rotated_at": "2026-01-01T00:00:00Z" }
The API key is missing, invalid, expired or revoked.
{ "error": "string", "message": "string", "meta": {} }
The key lacks the scope named in meta.required (or the level in meta.required_level), is used from an IP it does not allow, or the account is suspended.
{ "error": "string", "message": "string", "meta": {} }
No such resource, or it does not belong to the key's owner.
{ "error": "string", "message": "string", "meta": {} }
The request conflicts with the resource's current state; error names why.
{ "error": "string", "message": "string", "meta": {} }
Too many requests for this key; retry after the Retry-After seconds.
{ "error": "string", "message": "string", "meta": {} }
Something failed on our side and was logged; read the resource again before retrying a change.
{ "error": "string", "message": "string", "meta": {} }
/api/v1/scraping/plans/{plan}/credentials/reset Reset the credentials
POST /api/v1/scraping/plans/{plan}/credentials/resetIssues a new API key and answers it with Cache-Control: no-store; the old key stops working at once, so update every integration that uses it. 409 as for GET /plans/{plan}/credentials. 502 upstream_error: Datafuel refused and the old key still works. 503 unavailable: Datafuel could not be reached and nothing changed, so retry later. 504 outcome_unknown: Datafuel did not confirm, the key may have changed, so read the credentials before retrying. 429 upstream_rate_limited carries Retry-After.
Requires the api.scraping.manage scope. Every call is recorded in the account's audit log.
plan REQUIREDstringcurl https://api.datafuel.ai/api/v1/scraping/plans/{plan}/credentials/reset \ --request POST \ --header 'Authorization: Bearer df_live_your_key_here'
OK.
{ "api_key": "string", "rotated_at": "2026-01-01T00:00:00Z" }
The API key is missing, invalid, expired or revoked.
{ "error": "string", "message": "string", "meta": {} }
The key lacks the scope named in meta.required (or the level in meta.required_level), is used from an IP it does not allow, or the account is suspended.
{ "error": "string", "message": "string", "meta": {} }
No such resource, or it does not belong to the key's owner.
{ "error": "string", "message": "string", "meta": {} }
The request conflicts with the resource's current state; error names why.
{ "error": "string", "message": "string", "meta": {} }
Too many requests for this key; retry after the Retry-After seconds.
{ "error": "string", "message": "string", "meta": {} }
Something failed on our side and was logged; read the resource again before retrying a change.
{ "error": "string", "message": "string", "meta": {} }
The upstream provider refused the request; nothing was changed.
{ "error": "string", "message": "string", "meta": {} }
Temporarily unavailable; nothing was changed, try again shortly.
{ "error": "string", "message": "string", "meta": {} }
Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.
{ "error": "string", "message": "string", "meta": {} }
/api/v1/scraping/plans/{plan}/auto-top-up Get the auto top-up
GET /api/v1/scraping/plans/{plan}/auto-top-upThe plan's auto top-up rule, null when none is set, and the limits a rule must respect.
Requires the api.scraping.read scope.
plan REQUIREDstringcurl https://api.datafuel.ai/api/v1/scraping/plans/{plan}/auto-top-up \ --header 'Authorization: Bearer df_live_your_key_here'
OK.
{ "rule": { "status": "armed", "reason": "string", "threshold_credits": 0, "amount_credits": 0, "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "max_per_day": 0, "promo_code": "string", "payment": { "method": "balance", "card_id": "string" }, "last_fired_at": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" }, "limits": { "enabled": false, "min_threshold_credits": 0, "min_amount_credits": 0, "max_amount_credits": 0, "max_per_day": 0 } }
The API key is missing, invalid, expired or revoked.
{ "error": "string", "message": "string", "meta": {} }
The key lacks the scope named in meta.required (or the level in meta.required_level), is used from an IP it does not allow, or the account is suspended.
{ "error": "string", "message": "string", "meta": {} }
No such resource, or it does not belong to the key's owner.
{ "error": "string", "message": "string", "meta": {} }
Too many requests for this key; retry after the Retry-After seconds.
{ "error": "string", "message": "string", "meta": {} }
Something failed on our side and was logged; read the resource again before retrying a change.
{ "error": "string", "message": "string", "meta": {} }
/api/v1/scraping/plans/{plan}/auto-top-up Set the auto top-up
PUT /api/v1/scraping/plans/{plan}/auto-top-upCreates the plan's rule or replaces its settings. paused left out keeps the rule's status (a new rule starts armed), true pauses it and false re-arms a paused or suspended rule. While armed, it buys amount_credits whenever the balance falls to threshold_credits or below, charged without asking to payment (the balance, a saved card from GET /api/v1/payment-methods, or the default card when card_id is left out) and outside this key's monthly spending limit, which is why it needs the purchase level. A top-up the card refuses, or one charged to a card that was since removed, fails like one the balance cannot cover. 409 auto_top_up_disabled while auto top-up is turned off (limits.enabled), auto_top_up_blocked while support has blocked the rule.
Requires the api.scraping.purchase scope.
plan REQUIREDstringthreshold_creditsintegeramount_creditsintegerproduct_idstring | nullmax_per_dayintegerpromo_codestringpausedboolean | nullpaymentobject | nullcurl https://api.datafuel.ai/api/v1/scraping/plans/{plan}/auto-top-up \ --request PUT \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer df_live_your_key_here' \ --data '{ "threshold_credits": 5000, "amount_credits": 50000, "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "max_per_day": 0, "promo_code": "string", "paused": false, "payment": { "method": "balance", "card_id": "string" } }'
OK.
{ "rule": { "status": "armed", "reason": "string", "threshold_credits": 0, "amount_credits": 0, "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "max_per_day": 0, "promo_code": "string", "payment": { "method": "balance", "card_id": "string" }, "last_fired_at": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" }, "limits": { "enabled": false, "min_threshold_credits": 0, "min_amount_credits": 0, "max_amount_credits": 0, "max_per_day": 0 } }
The request is malformed: message maps each invalid field to its problem, or is a sentence when the body cannot be read at all.
{ "error": "string", "message": "string", "meta": {} }
The API key is missing, invalid, expired or revoked.
{ "error": "string", "message": "string", "meta": {} }
The key lacks the scope named in meta.required (or the level in meta.required_level), is used from an IP it does not allow, or the account is suspended.
{ "error": "string", "message": "string", "meta": {} }
No such resource, or it does not belong to the key's owner.
{ "error": "string", "message": "string", "meta": {} }
The request conflicts with the resource's current state; error names why.
{ "error": "string", "message": "string", "meta": {} }
Too many requests for this key; retry after the Retry-After seconds.
{ "error": "string", "message": "string", "meta": {} }
Something failed on our side and was logged; read the resource again before retrying a change.
{ "error": "string", "message": "string", "meta": {} }
/api/v1/scraping/plans/{plan}/auto-top-up Remove the auto top-up
DELETE /api/v1/scraping/plans/{plan}/auto-top-upDeletes the plan's rule, so no more credits are bought automatically. 404 when the plan has none; 409 auto_top_up_blocked while support has blocked the rule.
Requires the api.scraping.manage scope.
plan REQUIREDstringcurl https://api.datafuel.ai/api/v1/scraping/plans/{plan}/auto-top-up \ --request DELETE \ --header 'Authorization: Bearer df_live_your_key_here'
Done.
(empty body)The API key is missing, invalid, expired or revoked.
{ "error": "string", "message": "string", "meta": {} }
The key lacks the scope named in meta.required (or the level in meta.required_level), is used from an IP it does not allow, or the account is suspended.
{ "error": "string", "message": "string", "meta": {} }
No such resource, or it does not belong to the key's owner.
{ "error": "string", "message": "string", "meta": {} }
The request conflicts with the resource's current state; error names why.
{ "error": "string", "message": "string", "meta": {} }
Too many requests for this key; retry after the Retry-After seconds.
{ "error": "string", "message": "string", "meta": {} }
Something failed on our side and was logged; read the resource again before retrying a change.
{ "error": "string", "message": "string", "meta": {} }
/api/v1/scraping/quote Price a plan
POST /api/v1/scraping/quoteWhat POST /orders with the same body would charge, including discounts, tax and the payment method's fee, or why it cannot be ordered, e.g. plan_held while you already hold a plan. Nothing is reserved. 404 for an unknown product; 422 promo_code_invalid for a promo code that cannot be used.
Requires the api.scraping.read scope.
product_id REQUIREDstringperiod_daysintegerpaymentobject | nullpromo_codestringcurl https://api.datafuel.ai/api/v1/scraping/quote \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer df_live_your_key_here' \ --data '{ "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "period_days": 1, "payment": { "method": "balance", "card_id": "string" }, "promo_code": "string" }'
OK.
{ "purchasable": false, "issues": [ { "code": "string", "message": "string", "field": "string", "limit": 0 } ], "net": 0, "discount": 0, "tax": 0, "fee": 0, "total": 0, "currency": "usd" }
The request is malformed: message maps each invalid field to its problem, or is a sentence when the body cannot be read at all.
{ "error": "string", "message": "string", "meta": {} }
The API key is missing, invalid, expired or revoked.
{ "error": "string", "message": "string", "meta": {} }
The key lacks the scope named in meta.required (or the level in meta.required_level), is used from an IP it does not allow, or the account is suspended.
{ "error": "string", "message": "string", "meta": {} }
No such resource, or it does not belong to the key's owner.
{ "error": "string", "message": "string", "meta": {} }
The request is well formed but cannot be carried out; error names why.
{ "error": "string", "message": "string", "meta": {} }
Too many requests for this key; retry after the Retry-After seconds.
{ "error": "string", "message": "string", "meta": {} }
Something failed on our side and was logged; read the resource again before retrying a change.
{ "error": "string", "message": "string", "meta": {} }
Temporarily unavailable; nothing was changed, try again shortly.
{ "error": "string", "message": "string", "meta": {} }
Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.
{ "error": "string", "message": "string", "meta": {} }
/api/v1/scraping/orders Buy a product
POST /api/v1/scraping/ordersCharges the balance or a saved card straight away, without asking the customer. A subscription product opens the subscription; a payg product adds its pack's credits, which never expire, and can be bought again at any time. 201 answers the plan; 202 means it is paid and still being set up, or the bank asked for 3-D Secure (order.action_url). order.plan_id is the plan's id once it is delivered, null before. You hold one subscription at most (the free default plan does not count); while you do, a new one is refused with plan_held. 404 for an unknown product.
Requires the api.scraping.purchase scope. Send a unique Idempotency-Key per order; repeating it with the same body answers the first order instead of charging again.
Idempotency-Key REQUIREDstringproduct_id REQUIREDstringperiod_daysintegerpayment REQUIREDobjectpromo_codestringcurl https://api.datafuel.ai/api/v1/scraping/orders \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer df_live_your_key_here' \ --header 'Idempotency-Key: your-idempotency-key' \ --data '{ "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "period_days": 1, "payment": { "method": "balance", "card_id": "string" }, "promo_code": "string" }'
A repeated Idempotency-Key: the order it placed first, with replayed: true.
{ "order": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "pending", "service": "string", "product": "string", "action": "new", "total": 0, "currency": "usd", "payment": { "method": "balance", "card_id": "string" }, "plan_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "action_url": "https://example.com", "error": { "code": "insufficient_balance", "message": "string" }, "replayed": false, "created_at": "2026-01-01T00:00:00Z", "paid_at": "2026-01-01T00:00:00Z" }, "plan": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "provisioning", "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "period_days": 0, "expires_at": "2026-01-01T00:00:00Z", "cycle": { "credits": 0, "used": 0, "started_at": "2026-01-01T00:00:00Z", "resets_at": "2026-01-01T00:00:00Z" }, "credits": { "balance": 0, "plan": 0, "payg": 0, "used_24h": 0, "stale": false }, "concurrency": { "current": 0, "limit": 0 }, "created_at": "2026-01-01T00:00:00Z", "api_key_preview": "string" } }
Paid and delivered.
{ "order": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "pending", "service": "string", "product": "string", "action": "new", "total": 0, "currency": "usd", "payment": { "method": "balance", "card_id": "string" }, "plan_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "action_url": "https://example.com", "error": { "code": "insufficient_balance", "message": "string" }, "replayed": false, "created_at": "2026-01-01T00:00:00Z", "paid_at": "2026-01-01T00:00:00Z" }, "plan": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "provisioning", "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "period_days": 0, "expires_at": "2026-01-01T00:00:00Z", "cycle": { "credits": 0, "used": 0, "started_at": "2026-01-01T00:00:00Z", "resets_at": "2026-01-01T00:00:00Z" }, "credits": { "balance": 0, "plan": 0, "payg": 0, "used_24h": 0, "stale": false }, "concurrency": { "current": 0, "limit": 0 }, "created_at": "2026-01-01T00:00:00Z", "api_key_preview": "string" } }
Paid and still being delivered (poll GET /api/v1/orders/{id}), or waiting for 3-D Secure at order.action_url.
{ "order": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "pending", "service": "string", "product": "string", "action": "new", "total": 0, "currency": "usd", "payment": { "method": "balance", "card_id": "string" }, "plan_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "action_url": "https://example.com", "error": { "code": "insufficient_balance", "message": "string" }, "replayed": false, "created_at": "2026-01-01T00:00:00Z", "paid_at": "2026-01-01T00:00:00Z" }, "plan": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "provisioning", "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "period_days": 0, "expires_at": "2026-01-01T00:00:00Z", "cycle": { "credits": 0, "used": 0, "started_at": "2026-01-01T00:00:00Z", "resets_at": "2026-01-01T00:00:00Z" }, "credits": { "balance": 0, "plan": 0, "payg": 0, "used_24h": 0, "stale": false }, "concurrency": { "current": 0, "limit": 0 }, "created_at": "2026-01-01T00:00:00Z", "api_key_preview": "string" } }
The request is malformed: message maps each invalid field to its problem, or is a sentence when the body cannot be read at all.
{ "error": "string", "message": "string", "meta": {} }
The API key is missing, invalid, expired or revoked.
{ "error": "string", "message": "string", "meta": {} }
The payment was declined; error names why and meta.order is the failed order.
{ "error": "string", "message": "string", "meta": {} }
The key lacks the scope named in meta.required, is used from an IP it does not allow, the order would pass the key's monthly spending limit (spend_limit_exceeded), or the account is suspended.
{ "error": "string", "message": "string", "meta": {} }
No such product or plan, or it does not belong to the key's owner.
{ "error": "string", "message": "string", "meta": {} }
in_progress: another order of the account is still being placed, retry shortly with the same key; idempotency_conflict: the Idempotency-Key was already used for a different order; duplicate_request: the key was already used and its order is still being recorded, look it up instead of sending it again.
{ "error": "string", "message": "string", "meta": {} }
The order cannot be placed; error names why: not_purchasable (with meta.issues when the order itself is at fault, e.g. out of stock), promo_code_invalid, amount_too_small or payment_rejected.
{ "error": "string", "message": "string", "meta": {} }
Too many requests for this key; retry after the Retry-After seconds.
{ "error": "string", "message": "string", "meta": {} }
Something failed on our side and was logged; read the resource again before retrying a change.
{ "error": "string", "message": "string", "meta": {} }
Temporarily unavailable; nothing was changed, try again shortly.
{ "error": "string", "message": "string", "meta": {} }
Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.
{ "error": "string", "message": "string", "meta": {} }
/api/v1/scraping/plans/{plan}/quote Price credits
POST /api/v1/scraping/plans/{plan}/quoteWhat POST /plans/{plan}/orders with the same body would charge. Credits are topped up on a subscription only, at its term's top_up_per_thousand: the term's price per credit. 422 not_purchasable without a subscription or while credits are not on sale, promo_code_invalid for a promo code that cannot be used.
Requires the api.scraping.read scope.
plan REQUIREDstringcredits REQUIREDintegerpaymentobject | nullpromo_codestringcurl https://api.datafuel.ai/api/v1/scraping/plans/{plan}/quote \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer df_live_your_key_here' \ --data '{ "credits": 50000, "payment": { "method": "balance", "card_id": "string" }, "promo_code": "string" }'
OK.
{ "purchasable": false, "issues": [ { "code": "string", "message": "string", "field": "string", "limit": 0 } ], "net": 0, "discount": 0, "tax": 0, "fee": 0, "total": 0, "currency": "usd" }
The request is malformed: message maps each invalid field to its problem, or is a sentence when the body cannot be read at all.
{ "error": "string", "message": "string", "meta": {} }
The API key is missing, invalid, expired or revoked.
{ "error": "string", "message": "string", "meta": {} }
The key lacks the scope named in meta.required (or the level in meta.required_level), is used from an IP it does not allow, or the account is suspended.
{ "error": "string", "message": "string", "meta": {} }
No such resource, or it does not belong to the key's owner.
{ "error": "string", "message": "string", "meta": {} }
The request is well formed but cannot be carried out; error names why.
{ "error": "string", "message": "string", "meta": {} }
Too many requests for this key; retry after the Retry-After seconds.
{ "error": "string", "message": "string", "meta": {} }
Something failed on our side and was logged; read the resource again before retrying a change.
{ "error": "string", "message": "string", "meta": {} }
Temporarily unavailable; nothing was changed, try again shortly.
{ "error": "string", "message": "string", "meta": {} }
Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.
{ "error": "string", "message": "string", "meta": {} }
/api/v1/scraping/plans/{plan}/orders Buy credits
POST /api/v1/scraping/plans/{plan}/ordersAdds credits to the plan's pay-as-you-go balance, charged straight away. Credits are bought in whole thousands and never expire. order.plan_id is the plan's id.
Requires the api.scraping.purchase scope. Send a unique Idempotency-Key per order; repeating it with the same body answers the first order instead of charging again.
plan REQUIREDstringIdempotency-Key REQUIREDstringcredits REQUIREDintegerpayment REQUIREDobjectpromo_codestringcurl https://api.datafuel.ai/api/v1/scraping/plans/{plan}/orders \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer df_live_your_key_here' \ --header 'Idempotency-Key: your-idempotency-key' \ --data '{ "credits": 50000, "payment": { "method": "balance", "card_id": "string" }, "promo_code": "string" }'
A repeated Idempotency-Key: the order it placed first, with replayed: true.
{ "order": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "pending", "service": "string", "product": "string", "action": "new", "total": 0, "currency": "usd", "payment": { "method": "balance", "card_id": "string" }, "plan_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "action_url": "https://example.com", "error": { "code": "insufficient_balance", "message": "string" }, "replayed": false, "created_at": "2026-01-01T00:00:00Z", "paid_at": "2026-01-01T00:00:00Z" }, "plan": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "provisioning", "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "period_days": 0, "expires_at": "2026-01-01T00:00:00Z", "cycle": { "credits": 0, "used": 0, "started_at": "2026-01-01T00:00:00Z", "resets_at": "2026-01-01T00:00:00Z" }, "credits": { "balance": 0, "plan": 0, "payg": 0, "used_24h": 0, "stale": false }, "concurrency": { "current": 0, "limit": 0 }, "created_at": "2026-01-01T00:00:00Z", "api_key_preview": "string" } }
Paid and delivered.
{ "order": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "pending", "service": "string", "product": "string", "action": "new", "total": 0, "currency": "usd", "payment": { "method": "balance", "card_id": "string" }, "plan_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "action_url": "https://example.com", "error": { "code": "insufficient_balance", "message": "string" }, "replayed": false, "created_at": "2026-01-01T00:00:00Z", "paid_at": "2026-01-01T00:00:00Z" }, "plan": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "provisioning", "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "period_days": 0, "expires_at": "2026-01-01T00:00:00Z", "cycle": { "credits": 0, "used": 0, "started_at": "2026-01-01T00:00:00Z", "resets_at": "2026-01-01T00:00:00Z" }, "credits": { "balance": 0, "plan": 0, "payg": 0, "used_24h": 0, "stale": false }, "concurrency": { "current": 0, "limit": 0 }, "created_at": "2026-01-01T00:00:00Z", "api_key_preview": "string" } }
Paid and still being delivered (poll GET /api/v1/orders/{id}), or waiting for 3-D Secure at order.action_url.
{ "order": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "pending", "service": "string", "product": "string", "action": "new", "total": 0, "currency": "usd", "payment": { "method": "balance", "card_id": "string" }, "plan_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "action_url": "https://example.com", "error": { "code": "insufficient_balance", "message": "string" }, "replayed": false, "created_at": "2026-01-01T00:00:00Z", "paid_at": "2026-01-01T00:00:00Z" }, "plan": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "provisioning", "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "period_days": 0, "expires_at": "2026-01-01T00:00:00Z", "cycle": { "credits": 0, "used": 0, "started_at": "2026-01-01T00:00:00Z", "resets_at": "2026-01-01T00:00:00Z" }, "credits": { "balance": 0, "plan": 0, "payg": 0, "used_24h": 0, "stale": false }, "concurrency": { "current": 0, "limit": 0 }, "created_at": "2026-01-01T00:00:00Z", "api_key_preview": "string" } }
The request is malformed: message maps each invalid field to its problem, or is a sentence when the body cannot be read at all.
{ "error": "string", "message": "string", "meta": {} }
The API key is missing, invalid, expired or revoked.
{ "error": "string", "message": "string", "meta": {} }
The payment was declined; error names why and meta.order is the failed order.
{ "error": "string", "message": "string", "meta": {} }
The key lacks the scope named in meta.required, is used from an IP it does not allow, the order would pass the key's monthly spending limit (spend_limit_exceeded), or the account is suspended.
{ "error": "string", "message": "string", "meta": {} }
No such product or plan, or it does not belong to the key's owner.
{ "error": "string", "message": "string", "meta": {} }
in_progress: another order of the account is still being placed, retry shortly with the same key; idempotency_conflict: the Idempotency-Key was already used for a different order; duplicate_request: the key was already used and its order is still being recorded, look it up instead of sending it again.
{ "error": "string", "message": "string", "meta": {} }
The order cannot be placed; error names why: not_purchasable (with meta.issues when the order itself is at fault, e.g. out of stock), promo_code_invalid, amount_too_small or payment_rejected.
{ "error": "string", "message": "string", "meta": {} }
Too many requests for this key; retry after the Retry-After seconds.
{ "error": "string", "message": "string", "meta": {} }
Something failed on our side and was logged; read the resource again before retrying a change.
{ "error": "string", "message": "string", "meta": {} }
Temporarily unavailable; nothing was changed, try again shortly.
{ "error": "string", "message": "string", "meta": {} }
Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.
{ "error": "string", "message": "string", "meta": {} }