Archives

An archive is a snapshot of one user account or one guild, built in the background. Create user archive and Create guild archive start one, and the routes below look it up and give you a download link.

The Admin API routes on this page need archive:view_all, or archive:trigger:user for user archives and archive:trigger:guild for guild archives. See ACL evaluation.

Archive object

An archive is building while completed_at and failed_at are both null. It is complete once completed_at is set and failed once failed_at is set. A retry clears failed_at and error_message, so a failed archive can read as building again. An archive is deleted at expires_at, 365 days after it was requested.

Structure

Field	Type	Description
archive_id	snowflake	The ID of the archive
subject_type	string	The archive subject type
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 was requested
started_at	?ISO8601 timestamp	The time construction began
completed_at	?ISO8601 timestamp	The time construction completed
failed_at	?ISO8601 timestamp	The time construction failed
file_size	?string	The size of the archive in bytes, as a decimal string
progress_percent	number	The construction progress from 0 to 100
progress_step	?string	The step the build last reported
error_message	?string	The failure text, if the build failed
download_url_expires_at	?ISO8601 timestamp	Set when the build completes, to the same time as expires_at
expires_at	?ISO8601 timestamp	The time the archive is deleted

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

Archive download object

This object uses camelCase field names.

Structure

Field	Type	Description
downloadUrl	string	The time-limited URL the archive file is fetched from
expiresAt	ISO8601 timestamp	The time the URL stops working, seven days after it was issued

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, newest first, with no pagination. Use a narrower filter to find older archives. Without requested_by, the API narrows all to the subject types your ACLs cover. With it, you get that account's archives of both subject types, whatever subject_type says.

Query parameters

Field	Type	Description
subject_type?	string	user, guild or all (default all)
subject_id?	snowflake	The subject whose archives are returned, with subject_type set to user or guild
requested_by?	snowflake	The admin account that requested the archives, ignored when subject_id is set
limit?	integer	The maximum number of archives to return (1-200, default 50)
include_expired?	boolean	Whether to include archives past their expires_at (default false)

Response body

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

Response

Status	Body	Condition
200	response body	The archives were returned
400	error response	INVALID_FORM_BODY when subject_id is set while subject_type is all
403	error response	MISSING_ACL when you don't have an ACL for this subject type

The rate limit is 200 requests per minute, on the admin:lookup bucket.

Get archive

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

Returns one archive object, or null archive when nothing matches or the archive has expired.

Response body

Field	Type	Description
archive	?archive object	The archive, or null when it was not found

Response

Status	Body	Condition
200	response body	The lookup ran, whether or not it found the archive
403	error response	MISSING_ACL when you don't have an ACL for this subject type

The rate limit is 200 requests per minute, on the admin:lookup bucket.

Get archive download link

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

Returns an archive download object for a completed archive. The URL points to Download signed file unless the instance uses presigned storage links.

The link needs no credentials

Anyone with the URL can download the archive for seven days, and nothing revokes it.

Response

Status	Body	Condition
200	archive download object	The link was issued
400	error response	HARVEST_NOT_READY, HARVEST_FAILED or HARVEST_EXPIRED when the archive is not downloadable
403	error response	MISSING_ACL when you don't have an ACL for this subject type
404	error response	UNKNOWN_HARVEST when nothing matches or the archive has expired

The rate limit is 200 requests per minute, on the admin:lookup bucket.

Download signed file

GET/v1/signed-downloads/{filename}Unauthenticated

Streams an archive or a report file from a link the Admin API gave out. The token expires after seven days for an archive and five minutes for a report file. On an instance that uses presigned storage links, this route always returns 404.

Query parameters

Field	Type	Description
token	string	Signed download token from the link (1-2,048 characters)

Request headers

Field	Type	Description
Range?	string	A byte range to fetch part of the file

Response

Status	Body	Condition
200	file bytes	The complete file was streamed
206	file bytes	The requested byte range was streamed
404	Not Found	The token is missing, invalid or expired, or the file is gone
416	Range Not Satisfiable	The range lies outside the file

The rate limit is 60 requests per minute, on the user:harvest:download_file bucket.