Skip to content

Live log tail as server-sent events.

GET
/v1/profiles/{id}/logs/stream
curl --request GET \
  --url 'https://api.opdns.io/v1/profiles/example/logs/stream?limit=100' \
  --cookie opdns_session=<opdns_session>

Token scope: logs:read. A text/event-stream of the profile’s new log rows, with the filters of the tail query. The server polls the log destination every second with the tail cursor: ClickHouse for cloud and both, the node over the link for self-hosted; none sends only heartbeats. Errors known before the stream starts (501 not_implemented, 503 node_offline, 400 invalid cursor, 429 too_many_streams when the account already holds the maximum number of open streams) are problem responses.

Events:

  • event: rows, id: <cursor>, data: a QueryResult JSON (shape tail) holding the new rows. The first event carries the latest rows (up to limit) unless the stream resumes. Sent only when there are rows.
  • event: partial, data: {"partial": true, "partial_reason": "node_reconnecting"}: a poll answered partially with no rows (a self-hosted profile’s node is between link sessions). Sent once until a complete poll; rows events carry the result’s own partial flag.
  • event: error, data: {"status", "code", "detail"}: a failure while streaming. Transient ones (node_offline, node_timeout, 5xx) are followed by further polls; after any other the stream ends.
  • A comment line : heartbeat every 15 s. Each heartbeat re-checks the session or token and the profile: a revoked credential or a deleted profile ends the stream (after an error event).

The event id is the tail cursor after that event’s rows. Reconnecting with Last-Event-ID (EventSource does so by itself) or ?cursor= resumes after it, without gaps or repeats. The server ends a stream after an hour; clients reconnect.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required

Public 6-character id; never 000000.

string
/^[a-z0-9]{6}$/

Query Parameters

Section titled “Query Parameters”
device
Array<string>

Device id; repeat for several.

status
Array<string>
Allowed values: allowed blocked rewritten error

Repeat for several.

qname
string
<= 253 characters

Substring match for search, exact name otherwise.

qtype
Array<integer>

Numeric DNS type; repeat for several.

list
Array<integer>

Blocking list id; repeat for several.

client_ip
string
limit
integer
default: 100 >= 1 <= 1000
cursor
string
<= 512 characters

Opaque, from a previous result’s next_cursor.

Header Parameters

Section titled “Header Parameters”
Last-Event-ID
string
<= 512 characters

The id of the last rows event received; resumes after it.

Responses

Section titled “Responses”

200

Section titled “200”

The event stream.

Media typetext/event-stream

Server-sent events, e.g.

retry: 2000

id: dDE3Mjc2MDQ4MDAwMDAwMDA6MTcyNzYwNDc5OTk5OTAwMDAwMDo0Mg
event: rows
data: {"shape":"tail","source":"clickhouse","columns":[...],"rows":[[...]],"next_cursor":"dDE3..."}

: heartbeat
string
Examples
Examplerows
id: dDE3Mjc2MDQ4MDAwMDAwMDA6MTcyNzYwNDc5OTk5OTAwMDAwMDo0Mg
event: rows
data: {"shape":"tail","source":"clickhouse","columns":[{"name":"ts","type":"time"}],"rows":[["2026-09-29T10:00:00Z"]],"next_cursor":"dDE3Mjc2MDQ4MDAwMDAwMDA6MTcyNzYwNDc5OTk5OTAwMDAwMDo0Mg"}

400

Section titled “400”

Malformed request.

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 invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict 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 second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended
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
Example
{
  "type": "https://opdns.io/problems/bad_request",
  "title": "Bad Request",
  "status": 400,
  "code": "bad_request",
  "detail": "invalid JSON body",
  "request_id": "5f2c9a0e7b1d4c38"
}

401

Section titled “401”

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 invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict 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 second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended
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
Example
{
  "type": "https://opdns.io/problems/unauthenticated",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthenticated",
  "detail": "authentication required",
  "request_id": "5f2c9a0e7b1d4c38"
}

403

Section titled “403”

Authenticated but not allowed: insufficient_scope, session_required, csrf_rejected, mfa_enrolment_required (restricted session), mfa_required (an operator action, or an admin-scoped token, from a session signed in with the password alone; not in dev), reauth_required (sign in again within five minutes), account_pending_deletion (the account is in its deletion cooling-off).

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 invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict 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 second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended
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
Example
{
  "type": "https://opdns.io/problems/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "the token lacks the profiles:write scope",
  "request_id": "5f2c9a0e7b1d4c38"
}

404

Section titled “404”

Not found (also for resources of another organisation).

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 invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict 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 second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended
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
Example
{
  "type": "https://opdns.io/problems/not_found",
  "title": "Not Found",
  "status": 404,
  "code": "not_found",
  "detail": "resource not found",
  "request_id": "5f2c9a0e7b1d4c38"
}

422

Section titled “422”

Field validation failed (validation_failed, unknown_list).

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 invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict 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 second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended
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
Example
{
  "type": "https://opdns.io/problems/validation_failed",
  "title": "Unprocessable Content",
  "status": 422,
  "code": "validation_failed",
  "detail": "the request has invalid fields",
  "errors": [
    {
      "field": "settings.block_mode",
      "message": "one of nxdomain, refused, null, block-page"
    }
  ],
  "request_id": "5f2c9a0e7b1d4c38"
}

429

Section titled “429”

Rate limited (rate_limited).

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 invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict 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 second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended
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
Example
{
  "type": "https://opdns.io/problems/rate_limited",
  "title": "Too Many Requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "too many requests",
  "request_id": "5f2c9a0e7b1d4c38",
  "retry_after": 6
}

Headers

Section titled “Headers”
Retry-After
integer

501

Section titled “501”

not_implemented (cloud log queries not configured on this server) or shape_unsupported (node too old).

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 invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict 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 second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended
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
Example
{
  "type": "https://opdns.io/problems/not_implemented",
  "title": "Not Implemented",
  "status": 501,
  "code": "not_implemented",
  "detail": "cloud log queries are not configured on this server",
  "request_id": "5f2c9a0e7b1d4c38"
}

503

Section titled “503”

node_offline: the profile’s logs live on a self-hosted node and no node is connected; node_busy: the node has too many queries in flight; relay_unavailable. Retry after Retry-After (also retry_after in the body).

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 invalid_credentials signup_closed invite_required waitlist_unavailable invalid_token token_expired token_used session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict 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 second_factor_required invalid_second_factor mfa_enrolment_required mfa_required reauth_required no_second_factor totp_already_enabled totp_not_enabled last_credential passkey_exists passkey_invalid passkeys_unavailable ceremony_invalid account_pending_deletion credential_required deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists invalid_recovery_code profile_not_empty invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports password_too_short password_too_long profile_suspended
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
Example
{
  "type": "https://opdns.io/problems/node_offline",
  "title": "Service Unavailable",
  "status": 503,
  "code": "node_offline",
  "detail": "no node of this profile is connected",
  "request_id": "5f2c9a0e7b1d4c38",
  "retry_after": 30
}

Headers

Section titled “Headers”
Retry-After
integer