Web scraping · User API

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

List products

The plans on sale. A subscription product grants a credit allowance each cycle for a price per term; payg only sets the price of credits bought as needed. 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

{
  "results": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "subscription",
      "name": "string",
      "tagline": "string",
      "description": "string",
      "allowance": {
        "credits": 0,
        "cycle_days": 0,
        "concurrency": 0
      },
      "prices": [
        {
          "period_days": 0,
          "price": 0
        }
      ],
      "credits": {
        "steps": [
          {
            "min_credits": null,
            "per_thousand": null
          }
        ]
      }
    }
  ],
  "count": 0,
  "limit": 0,
  "offset": 0
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

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

Get a product

The product with its allowance, the price of each term and what extra credits cost at its rate. The price per 1,000 credits of a purchase is the step of credits.steps with the highest min_credits the purchase reaches.

Requires the api.scraping.read scope.

Path

productREQUIRED

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

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "subscription",
  "name": "string",
  "tagline": "string",
  "description": "string",
  "allowance": {
    "credits": 0,
    "cycle_days": 0,
    "concurrency": 0
  },
  "prices": [
    {
      "period_days": 0,
      "price": 0
    }
  ],
  "credits": {
    "steps": [
      {
        "min_credits": 100000,
        "per_thousand": 0
      }
    ]
  }
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

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

{
  "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,
        "used_24h": 0,
        "stale": false
      },
      "concurrency": {
        "current": 0,
        "limit": 0
      },
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "count": 0,
  "limit": 0,
  "offset": 0
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

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

planREQUIRED

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

{
  "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,
    "used_24h": 0,
    "stale": false
  },
  "concurrency": {
    "current": 0,
    "limit": 0
  },
  "created_at": "2026-01-01T00:00:00Z",
  "api_key_preview": "string"
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

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

planREQUIRED

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

{
  "api_key": "string",
  "rotated_at": "2026-01-01T00:00:00Z"
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

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

planREQUIRED

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

{
  "api_key": "string",
  "rotated_at": "2026-01-01T00:00:00Z"
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

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

planREQUIRED

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

{
  "rule": {
    "status": "armed",
    "reason": "string",
    "threshold_credits": 0,
    "amount_credits": 0,
    "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
  }
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

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

planREQUIRED

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_creditsREQUIRED

integer

Credits to buy each time, in whole thousands, between limits.min_amount_credits and limits.max_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,
    "max_per_day": 0,
    "promo_code": "string",
    "paused": false,
    "payment": {
      "method": "balance",
      "card_id": "string"
    }
  }'

Response

{
  "rule": {
    "status": "armed",
    "reason": "string",
    "threshold_credits": 0,
    "amount_credits": 0,
    "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
  }
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

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

planREQUIRED

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

(empty body)

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "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_idREQUIRED

string

A subscription product's id from GET /products.

period_daysREQUIRED

integer

The period_days of one of the product's prices.

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

{
  "purchasable": false,
  "issues": [
    {
      "code": "string",
      "message": "string",
      "field": "string",
      "limit": 0
    }
  ],
  "net": 0,
  "discount": 0,
  "tax": 0,
  "fee": 0,
  "total": 0,
  "currency": "usd"
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

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

Subscribe to a plan

Charges the balance or a saved card straight away, without asking the customer, and opens the subscription. 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 plan at most; 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-KeyREQUIRED

string

A unique value per order, sent again only to retry the same order.

Request body

product_idREQUIRED

string

A subscription product's id from GET /products.

period_daysREQUIRED

integer

The period_days of one of the product's prices.

paymentREQUIRED

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

{
  "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,
      "used_24h": 0,
      "stale": false
    },
    "concurrency": {
      "current": 0,
      "limit": 0
    },
    "created_at": "2026-01-01T00:00:00Z",
    "api_key_preview": "string"
  }
}

{
  "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,
      "used_24h": 0,
      "stale": false
    },
    "concurrency": {
      "current": 0,
      "limit": 0
    },
    "created_at": "2026-01-01T00:00:00Z",
    "api_key_preview": "string"
  }
}

{
  "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,
      "used_24h": 0,
      "stale": false
    },
    "concurrency": {
      "current": 0,
      "limit": 0
    },
    "created_at": "2026-01-01T00:00:00Z",
    "api_key_preview": "string"
  }
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "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 priced per 1,000 at the highest step of the plan's product credits.steps the amount reaches. 422 not_purchasable while credits are not on sale, promo_code_invalid for a promo code that cannot be used.

Requires the api.scraping.read scope.

Path

planREQUIRED

string

The plan's id.

Request body

creditsREQUIRED

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

{
  "purchasable": false,
  "issues": [
    {
      "code": "string",
      "message": "string",
      "field": "string",
      "limit": 0
    }
  ],
  "net": 0,
  "discount": 0,
  "tax": 0,
  "fee": 0,
  "total": 0,
  "currency": "usd"
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

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

Buy credits

Adds credits to the plan's balance, charged straight away. Credits are bought in whole thousands and do not expire, unless a plan you hold lapses. 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

planREQUIRED

string

The plan's id.

Headers

Idempotency-KeyREQUIRED

string

A unique value per order, sent again only to retry the same order.

Request body

creditsREQUIRED

integer

Credits to add, in whole thousands.

paymentREQUIRED

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

{
  "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,
      "used_24h": 0,
      "stale": false
    },
    "concurrency": {
      "current": 0,
      "limit": 0
    },
    "created_at": "2026-01-01T00:00:00Z",
    "api_key_preview": "string"
  }
}

{
  "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,
      "used_24h": 0,
      "stale": false
    },
    "concurrency": {
      "current": 0,
      "limit": 0
    },
    "created_at": "2026-01-01T00:00:00Z",
    "api_key_preview": "string"
  }
}

{
  "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,
      "used_24h": 0,
      "stale": false
    },
    "concurrency": {
      "current": 0,
      "limit": 0
    },
    "created_at": "2026-01-01T00:00:00Z",
    "api_key_preview": "string"
  }
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}

{
  "error": "string",
  "message": "string",
  "meta": {}
}