METAGROK
API / filter-files-with-aip-160

API

Filter Files API listings with AIP-160

filter-files-with-aip-160

Narrow GET https://api.x.ai/v1/files to the uploads you care about by passing an AIP-160 filter query string, so you can find a PDF by MIME, a fuzzy filename, or files larger than a size threshold without paging the whole team library by hand. Official Files manage reference documents the filterable fields, operators, and examples on the same list endpoint that already supports limit, order, sort_by, and pagination_token. Authenticate with a Bearer inference key. Browse the same library visually on the Files page in console.x.ai.

What you need

An XAI_API_KEY that can list Files, a terminal with curl and preferably jq, and at least one uploaded file so the filter has something to match. Neighboring jobs include List, download, and delete Files API uploads for the unfiltered walk, Set a TTL on Files API uploads when expires_at matters, and List files with a public URL filter when you only need public-URL rows. More API jobs live on the API hub.

Filter the list

  1. Export the inference key outside of source control:
export XAI_API_KEY="your_api_key"
  1. Call list with a filter expression. URL-encode spaces and quotes in the shell, or put the expression in a tool that builds query strings for you:
# Fuzzy filename match
curl -G "https://api.x.ai/v1/files"   -H "Authorization: Bearer $XAI_API_KEY"   --data-urlencode 'filter=name:"quarterly report"'   | jq .

# Partial content type (pdf matches application/pdf)
curl -G "https://api.x.ai/v1/files"   -H "Authorization: Bearer $XAI_API_KEY"   --data-urlencode 'filter=content_type = "pdf"'   | jq .

# Size and created_at together
curl -G "https://api.x.ai/v1/files"   -H "Authorization: Bearer $XAI_API_KEY"   --data-urlencode 'filter=size_bytes > 1000000 AND created_at > "2024-01-01T00:00:00Z"'   | jq .

  1. Use the documented fields: name / file_name (fuzzy string), file_id (exact), size_bytes (integer), content_type (partial MIME), created_at and expires_at (RFC 3339), upload_status (for example "Complete"), and user_defined_id (exact). Operators include =, !=, >, >=, <, <=, plus AND, OR, and NOT.

  2. Keep pagination in the loop when a filtered page is full. Pass pagination_token from the previous response until data is shorter than limit (max 100). Filtering narrows rows; it does not remove the page ceiling.

Pitfalls

Sending an unencoded space or bare quote in the query string breaks the request before the API evaluates the expression. Treating content_type = "pdf" as an exact MIME equality misses that the docs describe a partial match. Expecting filter alone to return every historical match across pages fails when you stop after the first page that still hits limit.