Batch-get collection document metadata

Fetch metadata for many known file IDs in one Management API call with GET https://management-api.x.ai/v1/collections/{collection_id}/documents:batchGet. Use this when you already have IDs (from an upload receipt or your own store) and want status without paging the full list. Listing and single-doc poll: List and poll documents in a Grok collection.

Batch get

curl "https://management-api.x.ai/v1/collections/$COLLECTION_ID/documents:batchGet?file_ids=$FILE_ID_1&file_ids=$FILE_ID_2" \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

file_ids is required (repeat the query param once per id). Optional team_id when the key can see more than one team; otherwise the team comes from the credentials.

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['XAI_MANAGEMENT_API_KEY']}"}
collection_id = "collection_dbc087b1-6c99-493d-86c6-b401fee34a9d"
file_ids = [
    "file_55a709d4-8edc-4f83-84d9-9f04fe49f832",
    "file_94847856-a56f-4b1e-82dd-7fe0b3af43d9",
]
params = [("file_ids", fid) for fid in file_ids]
resp = requests.get(
    f"https://management-api.x.ai/v1/collections/{collection_id}/documents:batchGet",
    headers=headers,
    params=params,
)
resp.raise_for_status()
for doc in resp.json().get("documents", []):
    meta = doc.get("file_metadata") or {}
    print(meta.get("file_id"), doc.get("status"), doc.get("error_message"))

Each document includes file_metadata (file_id, name, size_bytes, content_type, timestamps), optional fields, status, and error_message. Statuses match the single-get path: DOCUMENT_STATUS_PROCESSING, DOCUMENT_STATUS_PROCESSED, DOCUMENT_STATUS_FAILED (plus unknown).

Pitfalls

• Batch get does not invent IDs. Pass the file_id values you already stored.
• Searching while status is still processing returns empty matches — poll until DOCUMENT_STATUS_PROCESSED.
• Management key for list/get/batchGet/delete. /v1/documents/search uses XAI_API_KEY.
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.