Data center proxies

Static data center IPs.

GET/api/v1/dc/productsscope: api.static.read

List products

The plans on sale and the periods each can be bought for. Prices depend on the quantity and locations, so ask POST /quote for one.

Requires the api.static.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/dc/products \
  --header 'Authorization: Bearer df_live_your_key_here'

Response

OK.

{
  "results": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "description": "string",
      "max_ips": 0,
      "period_days": [
        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/dc/products/{product}scope: api.static.read

Get a product

The product with every country and region it can be ordered in, its stock level and how many IPs one order may take there.

Requires the api.static.read scope.

Path

product REQUIRED

string

The product's id.

Request

cURL

curl https://api.datafuel.ai/api/v1/dc/products/{product} \
  --header 'Authorization: Bearer df_live_your_key_here'

Response

OK.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "description": "string",
  "max_ips": 0,
  "period_days": [
    0
  ],
  "locations": [
    {
      "country": "US",
      "region": "CA",
      "region_name": "California",
      "stock_level": "high",
      "max_ips": 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": {}
}

Temporarily unavailable; nothing was changed, try again shortly.

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

GET/api/v1/dc/plansscope: api.static.read

List your plans

Requires the api.static.read scope.

Query

limit

integer

How many results to return, 1–100. Default: 50.

offset

integer

How many results to skip. Default: 0.

status

string

Only plans in this state.

provisioning active past_due suspended expired

Request

cURL

curl https://api.datafuel.ai/api/v1/dc/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",
      "ips": 0,
      "period_days": 0,
      "expires_at": "2026-01-01T00:00:00Z",
      "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "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/dc/plans/{plan}scope: api.static.read

Get a plan

The plan with its authentication settings and locations. The username and password are at GET /plans/{plan}/credentials.

Requires the api.static.read scope.

Path

plan REQUIRED

string

The plan's id.

Request

cURL

curl https://api.datafuel.ai/api/v1/dc/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",
  "ips": 0,
  "period_days": 0,
  "expires_at": "2026-01-01T00:00:00Z",
  "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-01-01T00:00:00Z",
  "auth": {
    "mode": "credentials",
    "allowed_ips": [
      "string"
    ]
  },
  "replacements_left": 0,
  "locations": [
    {
      "country": "US",
      "region": "CA",
      "ips": 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/dc/plans/{plan}/proxiesscope: api.static.manage

List a plan's proxies

Every IP of the plan with its port and location, plus the credentials to use them with. It carries the password, so it needs the manage level and is never cached.

Requires the api.static.manage scope.

Path

plan REQUIRED

string

The plan's id.

Query

format

string

json (the default) or txt.

json txt

Request

cURL

curl https://api.datafuel.ai/api/v1/dc/plans/{plan}/proxies \
  --header 'Authorization: Bearer df_live_your_key_here'

Response

OK.

{
  "username": "string",
  "password": "string",
  "proxies": [
    {
      "ip": "string",
      "port": 0,
      "country": "string",
      "region": "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 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/dc/plans/{plan}/credentialsscope: api.static.manage

Get the credentials

The username and password every IP of the plan accepts in credentials mode. They are a secret, so reading them needs the manage level and the answer is never cached.

Requires the api.static.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/dc/plans/{plan}/credentials \
  --header 'Authorization: Bearer df_live_your_key_here'

Response

OK.

{
  "username": "string",
  "password": "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": {}
}

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

Reset the credentials

Issues a new password for every IP of the plan at once and answers the credentials; the old password stops working. The username stays. 409 plan_not_active unless the plan is active, plan_provisioning while some of its IPs are still being delivered.

Requires the api.static.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/dc/plans/{plan}/credentials/reset \
  --request POST \
  --header 'Authorization: Bearer df_live_your_key_here'

Response

OK.

{
  "username": "string",
  "password": "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": {}
}

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

PUT/api/v1/dc/plans/{plan}/authscope: api.static.manage

Set how the proxies authenticate

credentials asks for the username and password; ip lets only allowed_ips in. The list replaces the one the plan has. 409 plan_not_active unless the plan is active, plan_provisioning while some of its IPs are still being delivered.

Requires the api.static.manage scope.

Path

plan REQUIRED

string

The plan's id.

Request body

mode REQUIRED

string

credentials: connect with the username and password; ip: only allowed_ips may connect.

credentials ip

allowed_ips

array<string>

Replaces the whole list, at most 20 addresses; ip mode needs at least one.

Request

cURL

curl https://api.datafuel.ai/api/v1/dc/plans/{plan}/auth \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer df_live_your_key_here' \
  --data '{
    "mode": "credentials",
    "allowed_ips": [
      "string"
    ]
  }'

Response

OK.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "provisioning",
  "ips": 0,
  "period_days": 0,
  "expires_at": "2026-01-01T00:00:00Z",
  "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-01-01T00:00:00Z",
  "auth": {
    "mode": "credentials",
    "allowed_ips": [
      "string"
    ]
  },
  "replacements_left": 0,
  "locations": [
    {
      "country": "US",
      "region": "CA",
      "ips": 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": {}
}

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

POST/api/v1/dc/plans/{plan}/replacescope: api.static.manage

Replace the IPs

Swaps every IP of the plan for new ones in the same locations and spends one of replacements_left. Buy more with POST /plans/{plan}/orders. 409 plan_not_active unless the plan is active, plan_provisioning while some of its IPs are still being delivered, no_replacements_left when none are left.

Requires the api.static.manage scope.

Path

plan REQUIRED

string

The plan's id.

Request

cURL

curl https://api.datafuel.ai/api/v1/dc/plans/{plan}/replace \
  --request POST \
  --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",
  "ips": 0,
  "period_days": 0,
  "expires_at": "2026-01-01T00:00:00Z",
  "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-01-01T00:00:00Z",
  "auth": {
    "mode": "credentials",
    "allowed_ips": [
      "string"
    ]
  },
  "replacements_left": 0,
  "locations": [
    {
      "country": "US",
      "region": "CA",
      "ips": 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": {}
}

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

POST/api/v1/dc/quotescope: api.static.read

Price a new 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. Nothing is reserved. 404 when the product does not exist; 422 promo_code_invalid when the promo code is refused.

Requires the api.static.read scope.

Request body

product_id REQUIRED

string

A product id from GET /products.

period_days REQUIRED

integer

One of the product's period_days.

locations REQUIRED

array<object>

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/dc/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,
    "locations": [
      {
        "country": "US",
        "region": "CA",
        "ips": 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/dc/ordersscope: api.static.purchase

Buy a new plan

Charges the balance or a saved card straight away, without asking the customer, and delivers the plan. 201 answers the delivered plan; 202 means it is paid and still being delivered, or the bank asked for 3-D Secure (order.action_url). 404 when the product does not exist.

Requires the api.static.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 id from GET /products.

period_days REQUIRED

integer

One of the product's period_days.

locations REQUIRED

array<object>

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/dc/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,
    "locations": [
      {
        "country": "US",
        "region": "CA",
        "ips": 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",
    "ips": 0,
    "period_days": 0,
    "expires_at": "2026-01-01T00:00:00Z",
    "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-01-01T00:00:00Z",
    "auth": {
      "mode": "credentials",
      "allowed_ips": [
        "string"
      ]
    },
    "replacements_left": 0,
    "locations": [
      {
        "country": "US",
        "region": "CA",
        "ips": 0
      }
    ]
  }
}

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",
    "ips": 0,
    "period_days": 0,
    "expires_at": "2026-01-01T00:00:00Z",
    "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-01-01T00:00:00Z",
    "auth": {
      "mode": "credentials",
      "allowed_ips": [
        "string"
      ]
    },
    "replacements_left": 0,
    "locations": [
      {
        "country": "US",
        "region": "CA",
        "ips": 0
      }
    ]
  }
}

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",
    "ips": 0,
    "period_days": 0,
    "expires_at": "2026-01-01T00:00:00Z",
    "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-01-01T00:00:00Z",
    "auth": {
      "mode": "credentials",
      "allowed_ips": [
        "string"
      ]
    },
    "replacements_left": 0,
    "locations": [
      {
        "country": "US",
        "region": "CA",
        "ips": 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 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/dc/plans/{plan}/quotescope: api.static.read

Price an add-on

What POST /plans/{plan}/orders with the same body would charge. 422 promo_code_invalid when the promo code is refused.

Requires the api.static.read scope.

Path

plan REQUIRED

string

The plan's id.

Request body

replacements REQUIRED

integer

How many IP replacements to buy; each one swaps every IP of the plan once.

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/dc/plans/{plan}/quote \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer df_live_your_key_here' \
  --data '{
    "replacements": 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/dc/plans/{plan}/ordersscope: api.static.purchase

Buy an add-on

Buys more IP replacements for a plan you hold, charged straight away.

Requires the api.static.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

replacements REQUIRED

integer

How many IP replacements to buy; each one swaps every IP of the plan once.

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/dc/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 '{
    "replacements": 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",
    "ips": 0,
    "period_days": 0,
    "expires_at": "2026-01-01T00:00:00Z",
    "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-01-01T00:00:00Z",
    "auth": {
      "mode": "credentials",
      "allowed_ips": [
        "string"
      ]
    },
    "replacements_left": 0,
    "locations": [
      {
        "country": "US",
        "region": "CA",
        "ips": 0
      }
    ]
  }
}

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",
    "ips": 0,
    "period_days": 0,
    "expires_at": "2026-01-01T00:00:00Z",
    "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-01-01T00:00:00Z",
    "auth": {
      "mode": "credentials",
      "allowed_ips": [
        "string"
      ]
    },
    "replacements_left": 0,
    "locations": [
      {
        "country": "US",
        "region": "CA",
        "ips": 0
      }
    ]
  }
}

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",
    "ips": 0,
    "period_days": 0,
    "expires_at": "2026-01-01T00:00:00Z",
    "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-01-01T00:00:00Z",
    "auth": {
      "mode": "credentials",
      "allowed_ips": [
        "string"
      ]
    },
    "replacements_left": 0,
    "locations": [
      {
        "country": "US",
        "region": "CA",
        "ips": 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 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": {}
}

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

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