Search indexes

A search index holds the documents a search reads, and a rebuild writes those documents from current data. These two routes queue a rebuild and read its progress. The rebuild itself runs as the refreshSearchIndex background task described by Jobs.

Both routes require the ACL guild:lookup.

Search index names

index_name is one of the following values. A value outside the set fails path validation.

Value	Scope	Description
guilds	Instance-wide	Every guild, backing Admin guild search
users	Instance-wide	Every account, backing Admin user search
reports	Instance-wide	Every report, backing Admin report search
audit_logs	Instance-wide	Every Admin audit entry, backing Admin audit search
discovery¹	Instance-wide	Discovery metadata written onto the guild documents of approved listings
channel_messages²	One guild	Messages of every channel in one guild, requiring `guild_id`
guild_members³	One guild	Members of one guild, requiring `guild_id`
favorite_memes⁴	One user	Favourited memes of one user, requiring `user_id`

¹ This name has no index of its own. It reads every approved listing and writes its description, category, primary language, and tags onto the existing guild documents in batches of 200

² This name indexes no message itself. It clears the message documents of every channel in the guild, then queues one indexChannelMessages job for each channel

³ The rebuild clears the guild’s member documents first and stamps members_indexed_at on the guild when it finishes

⁴ No worker handler is registered for this name. The queued job fails before it writes any progress record

Every instance-wide name other than discovery deletes its documents before the first batch is written, so search over that index is incomplete for the whole run.

Search index refresh object

A receipt for one queued rebuild.

Structure

Field	Type	Description
success	boolean	Always true
job_id¹	string	The ID of the queued rebuild, used to read its progress

¹ The value is a snowflake rendered as a string. It addresses the progress record that Get search index refresh reads. It differs from the job_id of the Jobs ledger entry for the same rebuild, and appears there only inside that entry’s payload

Example

{
  "success": true,
  "job_id": "1501314428688998182"
}

Search index refresh progress object

Progress for one queued rebuild. The object has two shapes, selected by status.

Not found structure

Field	Type	Description
status	string	Always `not_found`

Progress structure

Field	Type	Description
status	string	One of `in_progress`, `completed`, or `failed`
index_type	string	The search index name being rebuilt
total?¹	number	The number of documents expected, present while the rebuild reports progress and once it completes
indexed?²	number	The number of documents written so far
started_at?³	ISO8601 timestamp	The time the rebuild last reported progress
completed_at?	ISO8601 timestamp	The time the rebuild finished, present only when `status` is `completed`
failed_at?	ISO8601 timestamp	The time the rebuild failed, present only when `status` is `failed`
error?	string	The failure text, present only when `status` is `failed`

¹ total is the same value as indexed while the rebuild runs and becomes the real total on completion. The discovery rebuild reports the approved listing count from its first batch onwards

² The unit is the document the handler writes. A channel_messages rebuild counts the channels it queued

³ Rewritten on every progress report, so its value moves forward while the rebuild runs

The failure write replaces the record with the status, the index type, the error text, and the failure time, so a failed record has neither total nor indexed.

Example

{
  "status": "in_progress",
  "index_type": "guilds",
  "total": 3000,
  "indexed": 3000,
  "started_at": "2026-08-31T09:12:44.118Z"
}

Refresh search index

POST/v1/admin/search/indexes/{index_name}/refreshes

Audit reason

Queues a rebuild of the named index. Requires guild:lookup. Returns a search index refresh object on success.

Path parameters

Field	Type	Description
index_name	string	The search index name to rebuild

JSON body

Every field is optional. Fluxer reads an absent or empty body as an empty object, so an instance-wide rebuild can send no body at all. A body that is not parseable JSON returns 400 INVALID_FORM_BODY with the validation code INVALID_FORMAT at the body path.

Field	Type	Description
guild_id?¹	snowflake	The ID of the guild whose copy of the index is rebuilt
user_id?²	snowflake	The ID of the user whose copy of the index is rebuilt

¹ Required by channel_messages and guild_members. Every other index name ignores it

² Required by favorite_memes. Every other index name ignores it

Fluxer records both values on the audit entry whenever they are supplied, including on an index name that ignores them.

Response

Status	Body	Condition
200	search index refresh object	The rebuild was queued
400	error response	`INVALID_FORM_BODY` because the scope ID the index name requires is missing, or the body is not parseable JSON
403	error response	`MISSING_PERMISSIONS` without `admin:authenticate`, or `MISSING_ACL` without `guild:lookup`
500	error response	The job could not be queued

A missing scope ID names guild_id or user_id in errors. Fluxer queues no job and records no audit entry for that failure.

Side effects

Fluxer rebuilds the named index from current data in batches of 1,000 documents. A guild-scoped rebuild does not check that the guild exists, so an unknown ID produces an empty index.

The job has an attempt budget of 1, so a rebuild that throws is not retried.

Fluxer records one Admin audit entry with the action queue_refresh_index, the target type search_index, and the target ID 0. Its metadata has index_type, job_id, and whichever of guild_id and user_id the request supplied. Fluxer emits no Gateway Dispatch.

Rate limit

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

Get search index refresh

GET/v1/admin/search/index-refreshes/{job_id}

Returns the search index refresh progress object for one queued rebuild. Requires guild:lookup.