Archives

An archive is a snapshot of one user account or one guild, built in the background and downloaded as a file. Create user archive and Create guild archive request one. The operations here read archive state and issue time-limited download URLs.

While FiveCord builds an archive, it leaves out any stored file that is missing from storage. Any other read or write failure fails that build attempt and sets failed_at.

Every operation needs an ACL covering the subject type it touches.

• A user archive needs archive:view_all or archive:trigger:user.
• A guild archive needs archive:view_all or archive:trigger:guild.
• Reading both types at once needs archive:view_all, or archive:trigger:user and archive:trigger:guild together.

An expired archive stops being readable

An archive becomes unavailable through these routes at expires_at, 365 days after it was requested. Its lifetime is never extended.

Archive object

An archive is in one of these lifecycle states. It is building while completed_at and failed_at are both null, complete once completed_at is set, and failed once failed_at is set. When FiveCord starts a new attempt at a failed archive, it clears failed_at and error_message, so the archive reads as building again while that attempt runs.

Structure

Field	Type	Description
archive_id	snowflake	The ID of the archive, used with its subject to address the record
subject_type	string	The archive subject type the record is stored under
subject_id	snowflake	The user or guild the archive was taken of
requested_by	snowflake	The Admin account that requested the archive
requested_at	ISO8601 timestamp	The time the archive record was created
started_at	?ISO8601 timestamp	The time construction began, or null while the task has not started
completed_at	?ISO8601 timestamp	The time construction completed, or null when it has not completed
failed_at	?ISO8601 timestamp	The time construction failed, or null when it has not failed
file_size1	?string	The size of the stored archive object in bytes, or null before completion
progress_percent2	number	The construction progress from 0 to 100
progress_step2	?string	The step the construction task last reported
error_message	?string	The failure text the construction task reported, or null when it has not failed
download_url_expires_at3	?ISO8601 timestamp	The cache expiry stamped on the stored archive object at completion, or null before completion
expires_at4	?ISO8601 timestamp	The time the archive stops being readable

¹ The size is a decimal string

² A new archive starts at 0 with the step Queued, and completion sets 100 and Completed. Failure leaves progress_percent where it was and sets the step to Failed

³ Written at completion using the archive’s fixed expires_at. Create archive download returns a URL with its own expiry

⁴ The value is 365 days after requested_at

Example

{
  "archive_id": "1501314428688998182",
  "subject_type": "user",
  "subject_id": "1478812292088791040",
  "requested_by": "1478812292088791041",
  "requested_at": "2026-08-14T11:02:03.000Z",
  "completed_at": "2026-08-14T11:06:41.000Z",
  "file_size": "48211904",
  "progress_percent": 100,
  "progress_step": "Completed",
  "expires_at": "2027-08-14T11:02:03.000Z"
}

Archive subject types

Value	Description
user	The archive captures one user account
guild	The archive captures one guild

List archives also accepts all as a filter value, and it is the default there. No path segment accepts it.

Archive download object

This object uses camelCase field names, unlike every other Admin response body.

Structure

Field	Type	Description
downloadUrl1	string	The time-limited URL the archive file is fetched from
expiresAt2	ISO8601 timestamp	The time this URL stops working

¹ The URL is a presigned object storage link with no Admin credential, so possession of it grants access until it expires

² The value is seven days after the grant was issued, regardless of the archive’s own expires_at

Example

{
  "downloadUrl": "https://storage.example.com/harvests/1501314428688998182.zip?signature=abc123",
  "expiresAt": "2026-09-07T11:06:41.000Z"
}

List archives

GET/v1/admin/archivesAudit reason

Returns archive objects matching the supplied filters, newest first. Requires an ACL covering the requested subject_type.

Query parameters

Field	Type	Description
subject_type?1	string	user, guild, or all (default all)
subject_id?2	snowflake	The exact subject whose archives are returned
requested_by?3	snowflake	The Admin account that requested the returned archives
limit?4	integer	The maximum number of archives to return (1-200, default 50)
include_expired?5	boolean	Whether to include archives past their expires_at (default false)

¹ all returns the newest limit archives across both subject types, so a busy subject type can crowd out the other

² subject_type also has to name user or guild

³ Ignored when subject_id is supplied. When requested_by applies, FiveCord ignores subject_type and returns that account’s archives of both subject types

⁴ The listing is not paginated and returns no cursor. Only a narrower filter reaches older records

⁵ The value counts as true only for true, True, or 1. Excluding expired archives can leave fewer than limit results

The default filter narrows to the account’s ACLs

all is the default, and FiveCord resolves it to the subject types the account’s ACLs cover. An account holding only archive:trigger:user reads user archives, one holding only archive:trigger:guild reads guild archives, and one holding archive:view_all reads both. An account holding none of the three is refused with 403 MISSING_ACL.

Response body

Field	Type	Description
archives	array[archive object]	The archives matching the filters, newest first

Response

Status	Body	Condition
200	response body	The archives were returned
400	error response	subject_id is supplied while subject_type is all. INVALID_FORM_BODY has INVALID_FORMAT on subject_type
403	error response	MISSING_ACL without an ACL covering the requested subject type

Side effects

The operation records one Admin audit entry with action list_archives, target type archive, target ID 0, and metadata keys subject_type, limit, include_expired, and result_count. subject_type is the value after FiveCord narrows all to the account’s ACLs. The entry also has subject_user_id or subject_guild_id when subject_id is supplied, and requested_by_user_id when requested_by is supplied.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Get archive

GET/v1/admin/archives/{subject_type}/{subject_id}/{archive_id}Audit reason

Returns one archive object. Requires an ACL covering the subject type.

Path parameters

Field	Type	Description
subject_type	string	The archive subject type, either user or guild
subject_id	snowflake	The user or guild the archive was taken of
archive_id	snowflake	The ID of the archive

Response body

Field	Type	Description
archive1	?archive object	The archive, or null when the subject and identifier resolve to nothing

¹ A missing archive answers 200 with a null archive, which is also the answer when the identifier belongs to a different subject and when the archive has passed expires_at

Response

Status	Body	Condition
200	response body	A lookup was done, whether or not it resolved
403	error response	MISSING_ACL without an ACL covering the subject type

Side effects

The read issues no download grant.

The operation records one Admin audit entry with action get_archive, target type equal to subject_type, target ID equal to subject_id, and metadata keys archive_id and found. found is false when the response has a null archive.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Create archive download

GET/v1/admin/archives/{subject_type}/{subject_id}/{archive_id}/downloadAudit reason

Issues a temporary download URL for a completed archive. Returns an archive download object on success. Requires an ACL covering the subject type.

The grant is an unauthenticated bearer URL

The URL has its own signature and works for seven days for anyone who holds it. It is bound to no Admin account, and no operation revokes it. Each repeat of the operation issues a further independent grant.

Path parameters

Field	Type	Description
subject_type	string	The archive subject type, either user or guild
subject_id	snowflake	The user or guild the archive was taken of
archive_id	snowflake	The ID of a completed archive

Response

Status	Body	Condition
200	archive download object	The grant was issued
4001	error response	The archive is not downloadable, returned as HARVEST_NOT_READY, HARVEST_FAILED, or HARVEST_EXPIRED
403	error response	MISSING_ACL without an ACL covering the subject type
4042	error response	The subject and identifier resolve to nothing, returned as UNKNOWN_HARVEST

¹ HARVEST_FAILED while failed_at is set, HARVEST_NOT_READY while the archive has no completion time or no stored object, and HARVEST_EXPIRED once expires_at has passed, tested in that order

² The archive record stops being readable at expires_at, so an archive past its expiry answers UNKNOWN_HARVEST, not HARVEST_EXPIRED

Side effects

The operation creates a presigned download URL valid for seven days and changes no field of the archive, including download_url_expires_at.

The operation records one Admin audit entry with action get_archive_download_url, target type equal to subject_type, target ID equal to subject_id, and metadata key archive_id. The entry has no URL. A request that returns 400 or 404 records no entry.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.