Skip to content
Log inDashboard

The PoP catalogue.

GET
/v1/pops
curl --request GET \
--url https://api.opdns.io/v1/pops

Every PoP of this deployment’s fleet inventory that has a location, sorted by id, with its live status, for the dashboard map, the landing page’s globe and the status page. id is the value the top_pops analytics shape reports; name is the label to show (the city); region is the subdivision code shown after it when the inventory has one; country is ISO 3166-1 alpha-2; lat and lon are WGS 84 degrees.

status follows what the PoP’s servers report (each server’s anycast guard, every 30 seconds and on every change): serving when every server not drained for maintenance announces our addresses and passes its health checks, degraded when some do, down when none does or none has been heard from for 5 minutes, planned when the PoP is not in service yet (none of its servers counts; a planned PoP may list no server yet). How changes roll out across PoPs is not part of it. A deployment that does not follow its servers’ reports lists serving or planned only. Who hosts a PoP is not part of it. health_updated_at is when a server of the PoP was last heard from; servers lists each server’s own state, unknown when it has not been heard from lately.

Which PoPs exist and where follows the inventory the deployment reads at start. Cacheable for 15 seconds (Cache-Control: public, max-age=15). An empty array when the deployment lists no PoP.

PoPs.

Media typeapplication/json
Array<object>
object
id
required

Short PoP id, as in top_pops rows and log records (pop).

string
name
required

Label to show.

string
city
required
string
country
required

ISO 3166-1 alpha-2.

string
/^[A-Z]{2}$/
region

Subdivision code (ISO 3166-2 without the country), when the inventory has one; shown after the city in place of the country.

string
lat
required
number
>= -90 <= 90
lon
required
number
>= -180 <= 180
status
required

serving, degraded (some servers out), down (none answering) or planned (not in service yet).

string
Allowed values: serving degraded down planned
health_updated_at

When a server of the PoP was last heard from; absent when none has been.

string format: date-time
servers
required

The PoP’s servers; empty for a PoP without servers yet.

Array<object>
object
name
required
string
state
required

announced or withdrawn as last reported within 5 minutes, else unknown.

string
Allowed values: announced withdrawn unknown
healthy

Whether it passes its own health checks; absent when unknown.

boolean
drained

Taken out of service for maintenance.

boolean
sessions

Its BGP sessions to the upstream network.

object
up
required
integer
total
required
integer
last_seen

When its report was last received.

string format: date-time
Example
[
{
"id": "ams",
"name": "Amsterdam",
"city": "Amsterdam",
"country": "NL",
"region": "NJ",
"status": "serving",
"servers": [
{
"name": "pop-ewr-1",
"state": "announced"
}
]
}
]

Rate limited (rate_limited). For an API token, the organisation’s plan rate is spent until RateLimit-Reset.

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/rate_limited",
"title": "Too Many Requests",
"status": 429,
"code": "rate_limited",
"detail": "Too many requests in a short time. Please wait a moment, then try again.",
"request_id": "5f2c9a0e7b1d4c38",
"retry_after": 6
}
Retry-After
integer
RateLimit-Limit
integer
>= 1

On every response to an API token: the organisation’s plan rate, requests per one-minute window (api_requests_per_minute).

RateLimit-Remaining
integer

On every response to an API token: the requests left to the organisation in the current window.

RateLimit-Reset
integer

On every response to an API token: seconds until the current window ends and the count resets.

RateLimit-Policy
string

On every response to an API token: the quota policy, <limit>;w=60.