Search result blocks

When your application runs its own search (a help-centre index, a product database, an internal wiki), you can hand the hits to the model as search result blocks. The model treats each block as a citable source, and answers come back with citations that point at the exact result and passage, the same way document citations do. It is the simplest way to get grounded, attributable answers in a retrieval system.

Request

{
  "model": "Amara S1.2",
  "messages": [{
    "role": "user",
    "content": [
      {
        "type": "search_result",
        "source": "https://help.example.com/refunds",
        "title": "Refund policy",
        "content": [
          { "type": "text", "text": "Refunds are issued to the original payment method within 3 working days." },
          { "type": "text", "text": "Sale items can be exchanged but not refunded." }
        ],
        "citations": { "enabled": true }
      },
      { "type": "text", "text": "Can I get my money back for a sale item?" }
    ]
  }]
}

Search result blocks can also be returned from a function tool: put them in the content of your tool result, and the model cites them in its next answer.

Response

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Sale items can be exchanged, but not refunded.",
      "annotations": [{
        "type": "search_result_citation",
        "source": "https://help.example.com/refunds",
        "title": "Refund policy",
        "search_result_index": 0,
        "start_block_index": 1,
        "end_block_index": 2,
        "cited_text": "Sale items can be exchanged but not refunded."
      }]
    }
  }]
}

search_result_index is the position of the search result block among all such blocks in the request, starting at 0. Block indexes are half-open: start is included, end is not.

Good practice

• Send the top 5 to 20 hits, not hundreds. Irrelevant results invite irrelevant citations.
• Keep each text block to one idea, so a citation points somewhere precise.
• Tell the model what to do when the results do not answer the question, for example “If none of the results answers it, say so and suggest contacting support.”

Cost

Search result text is billed as input tokens. Cited text in the response is not billed again as output.