Skip to content

List the federation outbox

GET
/admin/federation/outbox

Lists your instance’s outgoing federation deliveries, newest first. Each row is one activity on its way to one peer, or to one user on that peer, and shows how delivery is going.

The outbox dispatcher adds the rows from your instance’s activities. Today only activity about posts with explicit-share visibility gets rows, one for each peer or user the post is shared with; anything else never appears here. As shipped, activity about a post with public visibility stops the dispatcher, and nothing recorded after it is queued.

sent means the other instance accepted the delivery into its inbox, not that it acted on it. A row is failed when the receiver refused it, when the peer wasn’t enabled and connected, or after five failed tries; retry it with POST /admin/federation/outbox/{id}/requeue. cancelled rows were dropped by POST /admin/federation/peers/{id}/cancel-pending.

Filters combine. since is a lower bound on when a row was created. To get the next page, pass next_cursor back as cursor. A full page always comes with a cursor, even if nothing follows, and a cursor the server can’t read is ignored, so you get the first page again. A limit outside 1 to 500 is treated as 100.

As shipped, this endpoint doesn’t check who is calling: any request that reaches the API gets the list, whether or not it’s signed in.

peer_id
string format: uuid
status
string
Allowed values: queued sent failed cancelled
activity_type
string

Only rows for this activity type, matched exactly, such as Create, Like or aa:Share.

since
string format: date-time

RFC3339 timestamp; only rows created at or after this.

limit
integer
default: 100 >= 1 <= 500
cursor
string

Pagination cursor from a prior response (opaque).

Outbox rows matching the filter.

object
items
required
Array<object>

One outgoing delivery: an activity on its way to one peer, or to one user on that peer. The outbox dispatcher creates it from your activities, and the delivery worker sends it.

object
id
required
string format: uuid
activity_id
required

The local activity being delivered.

string format: uuid
peer_id
required
string format: uuid
target_user_url

The user on the peer this delivery is for. Left out when it’s for the whole peer.

string
nullable
status
required

Where delivery stands. The database also has a refused status, for deliveries held back because they needed encryption, but that refusal isn’t in effect yet.

string
Allowed values: queued sent failed cancelled
attempts
required

How many tries have failed with a retryable error. The fifth such failure marks the row failed without adding to the count, so it stops at 4. Retrying the row sets it back to 0.

integer
next_attempt_at
required

When a queued row is next due. Retries wait 30 seconds, 30 seconds, 5 minutes and then an hour. Once a row is sent or failed, this keeps its last value.

string format: date-time
last_attempt_at
string format: date-time
nullable
last_error

What went wrong on the most recent failed try. When the receiver refuses a batch it includes the receiver’s reason; for a single delivery it gives only the HTTP status. It stays after a later try succeeds or the row is retried.

string
sent_at

When the other instance accepted the delivery.

string format: date-time
nullable
delivered_with_key_id

The key ID of the HTTP signature on the delivery that was accepted.

string
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time
next_cursor

Pass this as cursor to get the next page. It’s included whenever the page is full.

string
nullable

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed