Skip to content
Extrovert Extrovert Docs

Resume domain setup and health updates after a disconnect

GET
/v1/domains/{domain}/events

Durable status history, scoped to this visible domain. Persist next_cursor and pass it as after on the same domain. Drain has_more pages immediately; otherwise wait poll_after_seconds. Setup continues while disconnected, but Extrovert cannot wake an agent whose host is not running.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
domain
required
string

The fully-qualified domain name (e.g. mail.acme.com).

Query Parameters

Section titled “Query Parameters ”
limit
integer
default: 50 >= 1 <= 100

Page size for the cursor-paginated agent surface (default 50; clamped to the 1-100 range).

after
string

Cursor from the previous page for this domain.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Domain status history

object
items
required
Array<object>
object
id
required
string
type
required

For example domain.ready, domain.action_required or domain.recovered.

string
domain
required
string
summary
required
string
data
required
object
domain
string
readiness

Authoritative domain outcome shared by the console, API, MCP and SDK. Show summary and next_action instead of interpreting verification_status, mode or dkim_status. ready_for_inboxes describes domain configuration only; creating an inbox still requires permission and available plan capacity. checked_at is the latest DNS observation, not an end-to-end mail test.

object
status
required
string
Allowed values: waiting_for_dns checking setting_up ready action_required needs_attention
label
required
string
summary
required
string
reason
required
string
action_required_by
required
string
Allowed values: customer extrovert none
next_action
required
string
Allowed values: check_dns_entries restore_dns wait create_inbox use_inbox ask_owner_to_create_inbox
ready_for_inboxes
required
boolean
checked_at
string format: date-time
next_check_at
string format: date-time
poll_after_seconds
required
integer
>= 1
inboxes

Omitted without inbox-read permission. Agent counts include only that agent’s visible inboxes.

object
scope
required
string
Allowed values: agent inbox selected_inboxes project organization
total
required
integer
ready
required
integer
setting_up
required
integer
needs_attention
required
integer
created_at
required
string format: date-time
next_cursor
required

Save this cursor and pass it as after to resume on this same domain.

string
has_more
required
boolean
poll_after_seconds
required
integer

400

Section titled “400 ”

Invalid request.

The canonical error envelope. error is a stable machine code.

object
error
required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string
Example
forbidden
message

Human-readable detail (never leaks internals).

string
Example
missing required scope
reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string
used

Consumed plus reserved units.

integer format: int64
delta

Requested additional units.

integer format: int64
limit
integer format: int64
remaining
integer format: int64
consumed
integer format: int64
reserved
integer format: int64
next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time
upgrade_required
boolean

401

Section titled “401 ”

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object
error
required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string
Example
forbidden
message

Human-readable detail (never leaks internals).

string
Example
missing required scope
reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string
used

Consumed plus reserved units.

integer format: int64
delta

Requested additional units.

integer format: int64
limit
integer format: int64
remaining
integer format: int64
consumed
integer format: int64
reserved
integer format: int64
next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time
upgrade_required
boolean

403

Section titled “403 ”

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object
error
required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string
Example
forbidden
message

Human-readable detail (never leaks internals).

string
Example
missing required scope
reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string
used

Consumed plus reserved units.

integer format: int64
delta

Requested additional units.

integer format: int64
limit
integer format: int64
remaining
integer format: int64
consumed
integer format: int64
reserved
integer format: int64
next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time
upgrade_required
boolean

404

Section titled “404 ”

Resource not found.

The canonical error envelope. error is a stable machine code.

object
error
required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string
Example
forbidden
message

Human-readable detail (never leaks internals).

string
Example
missing required scope
reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string
used

Consumed plus reserved units.

integer format: int64
delta

Requested additional units.

integer format: int64
limit
integer format: int64
remaining
integer format: int64
consumed
integer format: int64
reserved
integer format: int64
next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time
upgrade_required
boolean