User APIhttps://api.datafuel.ai
Help centerOpenAPI spec

Web scraping

Your Scraping API plan, its credits and its API key.

GET/api/v1/scraping/productsscope: api.scraping.read

List products

The 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.

Query
limit
integer
How many results to return, 1–100. Default: 50.
offset
integer
How many results to skip. Default: 0.
Request
cURL
curl https://api.datafuel.ai/api/v1/scraping/products \
  --header 'Authorization: Bearer df_live_your_key_here'
Response

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": {}
}

GET/api/v1/scraping/products/{product}scope: api.scraping.read

Get a 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.

Path
product REQUIRED
string
The product's id.
Request
cURL
curl https://api.datafuel.ai/api/v1/scraping/products/{product} \
  --header 'Authorization: Bearer df_live_your_key_here'
Response

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": {}
}

GET/api/v1/scraping/plansscope: api.scraping.read

List your plans

Your 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.

Query
limit
integer
How many results to return, 1–100. Default: 50.
offset
integer
How many results to skip. Default: 0.
Request
cURL
curl https://api.datafuel.ai/api/v1/scraping/plans \
  --header 'Authorization: Bearer df_live_your_key_here'
Response

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": {}
}

GET/api/v1/scraping/plans/{plan}scope: api.scraping.read

Get a 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.

Path
plan REQUIRED
string
The plan's id.
Request
cURL
curl https://api.datafuel.ai/api/v1/scraping/plans/{plan} \
  --header 'Authorization: Bearer df_live_your_key_here'
Response

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": {}
}

GET/api/v1/scraping/plans/{plan}/credentialsscope: api.scraping.manage

Get the credentials

The 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.

Path
plan REQUIRED
string
The plan's id.
Request
cURL
curl https://api.datafuel.ai/api/v1/scraping/plans/{plan}/credentials \
  --header 'Authorization: Bearer df_live_your_key_here'
Response

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": {}
}

POST/api/v1/scraping/plans/{plan}/credentials/resetscope: api.scraping.manage

Reset the credentials

Issues 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.

Path
plan REQUIRED
string
The plan's id.
Request
cURL
curl https://api.datafuel.ai/api/v1/scraping/plans/{plan}/credentials/reset \
  --request POST \
  --header 'Authorization: Bearer df_live_your_key_here'
Response

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": {}
}

GET/api/v1/scraping/plans/{plan}/auto-top-upscope: api.scraping.read

Get the auto top-up

The plan's auto top-up rule, null when none is set, and the limits a rule must respect.

Requires the api.scraping.read scope.

Path
plan REQUIRED
string
The plan's id.
Request
cURL
curl https://api.datafuel.ai/api/v1/scraping/plans/{plan}/auto-top-up \
  --header 'Authorization: Bearer df_live_your_key_here'
Response

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": {}
}

PUT/api/v1/scraping/plans/{plan}/auto-top-upscope: api.scraping.purchase

Set the auto top-up

Creates 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.

Path
plan REQUIRED
string
The plan's id.
Request body
threshold_credits
integer
Buy credits when the balance falls to this many or below; at least limits.min_threshold_credits.
amount_credits
integer
Credits to top up each time at your subscription's rate, in whole thousands, between limits.min_amount_credits and limits.max_amount_credits; left out when product_id is set.
product_id
string | null
A payg product from GET /products to buy again each time, instead of amount_credits.
max_per_day
integer
The most top-ups per UTC day; 0 or left out for limits.max_per_day.
promo_code
string
A promo code applied to every top-up; dropped once it is refused.
paused
boolean | null
Left out keeps the rule's status (a new rule starts armed); true pauses it; false re-arms a paused or suspended rule.
payment
object | null
What each top-up is charged to. Left out keeps the rule's payment; a new rule charges the balance.
Request
cURL
curl 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"
    }
  }'
Response

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": {}
}

DELETE/api/v1/scraping/plans/{plan}/auto-top-upscope: api.scraping.manage

Remove the auto top-up

Deletes 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.

Path
plan REQUIRED
string
The plan's id.
Request
cURL
curl https://api.datafuel.ai/api/v1/scraping/plans/{plan}/auto-top-up \
  --request DELETE \
  --header 'Authorization: Bearer df_live_your_key_here'
Response

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": {}
}

POST/api/v1/scraping/quotescope: api.scraping.read

Price a plan

What 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.

Request body
product_id REQUIRED
string
A product's id from GET /products.
period_days
integer
For a subscription, the period_days of one of the product's prices; ignored for payg.
payment
object | null
The payment method, when its fee should be included.
promo_code
string
A promo code; an invalid one is refused, never silently dropped.
Request
cURL
curl 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"
  }'
Response

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": {}
}

POST/api/v1/scraping/ordersscope: api.scraping.purchase

Buy a product

Charges 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.

Headers
Idempotency-Key REQUIRED
string
A unique value per order, sent again only to retry the same order.
Request body
product_id REQUIRED
string
A product's id from GET /products.
period_days
integer
For a subscription, the period_days of one of the product's prices; ignored for payg.
payment REQUIRED
object
promo_code
string
A promo code; an invalid one is refused, never silently dropped.
Request
cURL
curl 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"
  }'
Response

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": {}
}

POST/api/v1/scraping/plans/{plan}/quotescope: api.scraping.read

Price credits

What 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.

Path
plan REQUIRED
string
The plan's id.
Request body
credits REQUIRED
integer
Credits to add, in whole thousands.
payment
object | null
The payment method, when its fee should be included.
promo_code
string
A promo code; an invalid one is refused, never silently dropped.
Request
cURL
curl 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"
  }'
Response

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": {}
}

POST/api/v1/scraping/plans/{plan}/ordersscope: api.scraping.purchase

Buy credits

Adds 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.

Path
plan REQUIRED
string
The plan's id.
Headers
Idempotency-Key REQUIRED
string
A unique value per order, sent again only to retry the same order.
Request body
credits REQUIRED
integer
Credits to add, in whole thousands.
payment REQUIRED
object
promo_code
string
A promo code; an invalid one is refused, never silently dropped.
Request
cURL
curl 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"
  }'
Response

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": {}
}