Skip to content

Count a peer's shares and suggestions

GET
/admin/federation/peers/{id}/defederation-preview

Counts some of what deleting a peer would remove: unrevoked shares to it by object kind, suggestions saved from its public list, and whether its pairing is still pending.

It doesn’t cover everything a delete removes: the peer’s outbox and inbox rows, the accounts cached from it, and the comments and likes its users left go too (see DELETE /admin/federation/peers/{id}). The counts are read one after another when you ask, and nothing is held: the delete doesn’t use this preview, and the numbers can change before you delete.

Shares that have expired but haven’t been revoked yet are counted. pending_handshakes is 1 if this peer’s own status is pending_outbound or pending_inbound, otherwise 0. An unknown id gets 404. Needs the federation.read or system.admin capability.

id
required
string format: uuid

The counts for this peer.

Counts for one peer, read when you asked.

object
peer_id
required
string format: uuid
peer_display_name
required
string
peer_url
required
string
total_active_shares
required

Unrevoked shares to this peer across all object kinds, including expired ones the expiry job hasn’t revoked yet. Deleting the peer removes them without telling it.

integer format: int64
shares_by_kind
required

The same shares by object kind, such as post or collection. Kinds with none are left out.

object
key
additional properties
integer format: int64
pending_handshakes
required

1 if this peer’s pairing is still pending (pending_outbound or pending_inbound), otherwise 0.

integer
cached_suggestions
required

Suggestions saved from this peer’s public list. Deleting the peer removes them.

integer

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

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed