Skip to content
Log inDashboard

The organisation's plan, its limits and this month's usage.

GET
/v1/account/plan
curl --request GET \
--url https://api.opdns.io/v1/account/plan \
--cookie __Host-opdns_session=<__Host-opdns_session>

Token scope: account:read. Plans attach to the organisation. limits are the plan’s ceilings, usage what the organisation holds of the counted ones (linked_ips is the most any one profile holds), and queries the billable queries of the calendar month (UTC): every query the cloud resolved for its profiles, logged or counted, never one a self-hosted node resolved. queries.used is metered from the query counters at most a few minutes behind (null before the first metering); queries.state is what the resolvers apply: warn from 80 %, over at the limit, when the resolvers keep resolving and filtering but stop keeping query logs until reset_at or a larger plan. Profiles, linked addresses, nodes, retention and API tokens past a limit are refused with 422 plan_limit; requests with an API token past api_requests_per_minute (per organisation) get 429 rate_limited. provisional is true while the plan’s price or limits may still change before paid plans start. upgrade is the plan the organisation is offered next (its name, list price and limits, for upgrade prompts), null when there is none.

The plan.

Media typeapplication/json
object
plan
required
string
Allowed values: free personal family business
name
required
string
source
required

Who set the plan last.

string
Allowed values: default operator billing
changed_at
required
string | null format: date-time
provisional
required

The plan’s price or limits may still change before paid plans start.

boolean
price
required
object
currency
required
string
monthly
required

Whole currency units a month; null when priced on request.

integer | null
yearly
required

Whole currency units a year; null when priced on request.

integer | null
limits
required

A plan’s ceilings.

object
profiles
required

Live profiles per organisation.

integer
linked_ips
required

Linked addresses and DDNS slots per profile.

integer
nodes
required

Self-hosted nodes per organisation (enrolled, or pending with a valid code).

integer
queries_per_month
required

Billable queries per calendar month (UTC). Metered, never refused.

integer format: int64
log_retention_days
required

The longest log retention a profile may choose.

integer
api_tokens
required

Unexpired API tokens per organisation.

integer
api_requests_per_minute
required

Requests a minute with an API token, per organisation (429 past it).

integer
usage
required
object
profiles
required
integer
linked_ips
required

The most linked addresses and slots any one profile holds.

integer
nodes
required
integer
api_tokens
required
integer
queries
required
object
used
required

Billable queries so far this month; null before the first metering.

integer | null format: int64
limit
required
integer format: int64
ratio
required

Used / limit.

number | null
state
required

What the resolvers apply; over pauses query logs, never resolution or filtering.

string
Allowed values: ok warn over
warn_ratio
required

The share of the limit from which the state is warn (0.8).

number
period
required

The calendar month (UTC), YYYY-MM.

string
/^[0-9]{4}-[0-9]{2}$/
period_start
required
string format: date-time
reset_at
required

When usage starts again from zero (the next month, 00:00 UTC).

string format: date-time
metered_at
required
string | null format: date-time
upgrade_url
required
string format: uri
upgrade
required
One of:

A plan on offer, with its list price (whole currency units) and limits.

object
plan
required
string
Allowed values: free personal family business
name
required
string
price
required
object
currency
required
string
monthly
required

Whole currency units a month; null when priced on request.

integer | null
yearly
required

Whole currency units a year; null when priced on request.

integer | null
limits
required

A plan’s ceilings.

object
profiles
required

Live profiles per organisation.

integer
linked_ips
required

Linked addresses and DDNS slots per profile.

integer
nodes
required

Self-hosted nodes per organisation (enrolled, or pending with a valid code).

integer
queries_per_month
required

Billable queries per calendar month (UTC). Metered, never refused.

integer format: int64
log_retention_days
required

The longest log retention a profile may choose.

integer
api_tokens
required

Unexpired API tokens per organisation.

integer
api_requests_per_minute
required

Requests a minute with an API token, per organisation (429 past it).

integer
Example
{
"plan": "free",
"name": "Free",
"source": "default",
"changed_at": null,
"provisional": true,
"price": {
"currency": "USD",
"monthly": 0,
"yearly": 0
},
"limits": {
"profiles": 3,
"linked_ips": 20,
"nodes": 1,
"queries_per_month": 300000,
"log_retention_days": 30,
"api_tokens": 2,
"api_requests_per_minute": 120
},
"usage": {
"profiles": 2,
"linked_ips": 1,
"nodes": 0,
"api_tokens": 1
},
"queries": {
"used": 182340,
"limit": 300000,
"ratio": 0.6078,
"state": "ok",
"warn_ratio": 0.8,
"period": "2026-10",
"period_start": "2026-10-01T00:00:00Z",
"reset_at": "2026-11-01T00:00:00Z",
"metered_at": "2026-10-20T12:00:00Z"
},
"upgrade_url": "https://opdns.io/pricing/",
"upgrade": {
"plan": "personal",
"name": "Personal",
"price": {
"currency": "USD",
"monthly": 2,
"yearly": 10
},
"limits": {
"profiles": 10,
"linked_ips": 20,
"nodes": 3,
"queries_per_month": 5000000,
"log_retention_days": 90,
"api_tokens": 10,
"api_requests_per_minute": 300
}
}
}

Not authenticated.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required

Stable machine code.

string
Allowed values: bad_request body_too_large bad_if_match unauthenticated signup_closed invite_required waitlist_unavailable mail_unavailable invalid_token token_expired token_used email_unverified session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict managed_by_opwan no_opdns_account service_unavailable unknown_list too_many_rules validation_failed rate_limited internal node_revoked node_offline node_busy node_timeout node_error result_too_large shape_unsupported node_token_superseded relay_unavailable not_implemented query_timeout query_too_expensive range_too_large too_many_queries mfa_required reauth_required account_pending_deletion deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists profile_not_empty no_adoption_pending invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports profile_suspended plan_limit owner_required billing_unavailable billing_provider_error subscription_exists no_billing_account block_page_ca_exists oidc_unavailable feedback_status_conflict reply_not_wanted reply_unavailable
detail
string
errors
Array<object>
object
field
required
string
message
required
string
request_id
string
retry_after

Seconds, repeating the Retry-After header (rate limits, offline nodes).

integer
limit

The plan limit a plan_limit problem hit.

object
name
required
string
Allowed values: profiles linked_ips nodes queries_per_month log_retention_days api_tokens api_requests_per_minute
max
required

The plan’s value of the limit.

integer format: int64
plan
required
string
Allowed values: free personal family business
upgrade_url
required

Where to move to a larger plan.

string format: uri
required_scope

The scope the API token lacked (insufficient_scope).

string
Allowed values: profiles:read profiles:write nodes:write account:read billing:read logs:read analytics:read
Example
{
"type": "https://opdns.io/problems/unauthenticated",
"title": "Unauthorized",
"status": 401,
"code": "unauthenticated",
"detail": "You're not signed in, or your sign-in has ended. Please sign in again to continue.",
"request_id": "5f2c9a0e7b1d4c38"
}

Authenticated but not allowed: insufficient_scope, session_required, csrf_rejected, reauth_required (sign in again within five minutes), account_pending_deletion (the account is in its deletion cooling-off), email_unverified (creating a profile before the email address is verified).

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required

Stable machine code.

string
Allowed values: bad_request body_too_large bad_if_match unauthenticated signup_closed invite_required waitlist_unavailable mail_unavailable invalid_token token_expired token_used email_unverified session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict managed_by_opwan no_opdns_account service_unavailable unknown_list too_many_rules validation_failed rate_limited internal node_revoked node_offline node_busy node_timeout node_error result_too_large shape_unsupported node_token_superseded relay_unavailable not_implemented query_timeout query_too_expensive range_too_large too_many_queries mfa_required reauth_required account_pending_deletion deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists profile_not_empty no_adoption_pending invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports profile_suspended plan_limit owner_required billing_unavailable billing_provider_error subscription_exists no_billing_account block_page_ca_exists oidc_unavailable feedback_status_conflict reply_not_wanted reply_unavailable
detail
string
errors
Array<object>
object
field
required
string
message
required
string
request_id
string
retry_after

Seconds, repeating the Retry-After header (rate limits, offline nodes).

integer
limit

The plan limit a plan_limit problem hit.

object
name
required
string
Allowed values: profiles linked_ips nodes queries_per_month log_retention_days api_tokens api_requests_per_minute
max
required

The plan’s value of the limit.

integer format: int64
plan
required
string
Allowed values: free personal family business
upgrade_url
required

Where to move to a larger plan.

string format: uri
required_scope

The scope the API token lacked (insufficient_scope).

string
Allowed values: profiles:read profiles:write nodes:write account:read billing:read logs:read analytics:read
Example
{
"type": "https://opdns.io/problems/insufficient_scope",
"title": "Forbidden",
"status": 403,
"code": "insufficient_scope",
"detail": "This API token isn't allowed to do this: it needs the profiles:write scope. Create a token that includes it, then try again.",
"required_scope": "profiles:write",
"request_id": "5f2c9a0e7b1d4c38"
}