input_file and attachment_search in the Responses API

Two paths to the same block

The Grok Responses API accepts a document in two ways: via file_id, meaning a file you previously uploaded, or via file_url, a public address that xAI fetches at request time. The block uses the same name in both cases, input_file, and downstream processing is identical: Grok activates the attachment_search tool and extracts the passages that answer your question. What changes is the document lifecycle, its confidentiality, and the cost of each repeated call.

The file_id path

Once you send the file via POST /v1/files, you reference it by its identifier, along with your question in plain text:

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_id": "file_abc123"
    },
    {
      "type": "input_text",
      "text": "What are the main risks mentioned in this report?"
    }
  ]
}

This path makes sense in three situations. The first is repeated queries: if your legal team asks fifteen successive questions about the same contract, a single upload followed by fifteen references beats fifteen transfers of the same PDF. The second is confidentiality, when the document must not be exposed behind a URL accessible to anyone with the link. The third is your application architecture: if files are pre-uploaded during nightly ingestion, your requests handle only identifiers.

The file_url path

When the document is already published somewhere, upload becomes an unnecessary step and you can point directly to the address:

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_url": "https://exemple.com/specifications-api.pdf"
    },
    {
      "type": "input_text",
      "text": "Summarize the endpoints described in this documentation."
    }
  ]
}

Typical use cases include open documentation you have no reason to store, a file hosted on your own infrastructure behind a temporary URL, or a quick test where you want to verify a hypothesis without setting up an entire upload pipeline.

Three limitations come with this convenience, and all of them cost you in production. The URL must be truly public, with no authentication: an address protected by a token or cookie returns an error page to xAI, which the model will diligently analyze instead of your document. The download adds to the request processing time, making large PDFs significantly slower than with file_id. Finally, there is no cache on the xAI side: every call re-downloads the file, so a single document queried fifty times a day crosses the network fifty times.

What attachment_search does

As soon as an input_file appears in your request, Grok triggers attachment_search without any configuration on your part. Processing happens in four steps:

1. Content extraction from the file: text, tables, structure
2. Temporary indexing of this content, for the duration of the request
3. Search for relevant passages based on your question
4. Injection of excerpts into the model context

Focus on the adjective “temporary” in the second step, because it explains a cost difference many discover too late: the index is rebuilt on every call and disappears afterward. This is precisely the problem that collections solve with persistent indexing. Note also that the model cites the passages it actually used in its response, letting you verify its work rather than taking its word for it.

Combining multiple documents

Nothing forces you to stick to one file per request. By stacking multiple input_file blocks, you ask the model to reason across the set:

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_id": "file_rapport_q1"
    },
    {
      "type": "input_file",
      "file_id": "file_rapport_q2"
    },
    {
      "type": "input_text",
      "text": "Compare the Q1 and Q2 results."
    }
  ]
}

Grok analyzes both documents and cross-references information to answer, which opens the door to quarterly comparisons, reviews of successive contract versions, or confrontations between a specification and its implementation.

Choosing between the two

Key takeaways

• input_file with file_id references an uploaded file, file_url a public document
• The attachment_search tool activates automatically to extract relevant content
• You can combine multiple files in a single request
• Prefer file_id for confidential or frequently queried files
• Prefer file_url for public documents or quick tests