List and poll documents in a Grok collection

After you create a collection and upload documents, wait until each file reaches DOCUMENT_STATUS_PROCESSED before searching. Listing and get use the Management API (https://management-api.x.ai/v1) with a Management API key that has Collections permissions.

List documents

curl "https://management-api.x.ai/v1/collections/$COLLECTION_ID/documents?limit=100" \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

Optional query params: limit (max 100), order, sort_by (DOCUMENTS_SORT_BY_NAME | DOCUMENTS_SORT_BY_SIZE | DOCUMENTS_SORT_BY_AGE), pagination_token, and filter (AIP-160). Useful filters:

• status:DOCUMENT_STATUS_PROCESSED
• name:"quarterly" AND status:!DOCUMENT_STATUS_FAILED
• fields.isbn:"978-1-234567-89-0"
• size_bytes:>5000000 AND content_type:application/pdf

Each item includes file_metadata (file_id, name, size_bytes, content_type), optional fields, status, and error_message. Page with pagination_token from the response.

Get one document and poll until processed

curl "https://management-api.x.ai/v1/collections/$COLLECTION_ID/documents/$FILE_ID" \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

Statuses: DOCUMENT_STATUS_PROCESSING, DOCUMENT_STATUS_PROCESSED, DOCUMENT_STATUS_FAILED (plus unknown). Poll every few seconds until PROCESSED or FAILED.

import os
import time
from xai_sdk import Client
from xai_sdk.proto import collections_pb2

client = Client(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
)
collection_id = "collection_dbc087b1-6c99-493d-86c6-b401fee34a9d"
file_id = "file_55a709d4-8edc-4f83-84d9-9f04fe49f832"

doc = client.collections.get_document(file_id, collection_id)
while doc.status != collections_pb2.DOCUMENT_STATUS_PROCESSED:
    if doc.status == collections_pb2.DOCUMENT_STATUS_FAILED:
        raise RuntimeError(doc.error_message or "document failed")
    time.sleep(3)
    doc = client.collections.get_document(file_id, collection_id)
print(doc.file_metadata.file_id, doc.status)

Batch metadata for many ids: GET /v1/collections/{collection_id}/documents:batchGet?file_ids=....

Pitfalls

• Searching while status is still processing returns empty matches.
• List/get/delete need the management key. /v1/documents/search and chat file_search use the regular XAI_API_KEY.
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.