How do Perplexity Agent API source identifiers map to cited URLs?

Definition: As of 17 October 2026, Perplexity documents a source identifier as the integer id attached to a result inside an Agent API search_results output item. An inline citation marker refers to that id, and the matching result's url supplies the source link.

Key facts

• Perplexity's Web Search documentation defines id as a stable citation index and url as the source page's canonical URL.
• The Give it tools guide places built-in tool results in the response's output array alongside the assistant's message item.
• The Streaming Citation Parsing guide states that multiple search-result batches in a response share a single citation ID space.

How does a marker resolve to a URL?

The mapping uses the explicit identifier: [1] refers to the result whose id equals 1. Perplexity's Web Search reference says each number refers to a result's id and identifies the id and url fields as the source of truth for citations, regardless of whether markers appear.

A client therefore builds an identifier-to-URL lookup from the returned records. Matching a marker against an array position can misassign the link when results come from several searches. The identifier remains the lookup key when those records are collected together.

The same reference describes title as the returned page title and snippet as text extracted during search. These fields can supply a source card's label and preview while url supplies its destination.

Where should an integration collect the identifiers?

Perplexity's citation parsing example iterates every item in response.output and appends the results from each search_results item. The following Python excerpt matches that collection and lookup pattern for an SDK response:

search_results = []
for item in response.output:
    if item.type == "search_results":
        search_results.extend(item.results or [])

url_map = {r.id: r.url for r in search_results}

The same guide describes a streaming event named response.reasoning.search_results, with one event per search. A streaming client accumulates each event's results; replacing the saved collection with each new batch drops earlier records.

Answer text arrives through response.output_text.delta events. The guide parses accumulated text because a marker can split across chunks. This gives an integration both the complete marker and the collected records needed to resolve it.

How should a citation report distinguish results from references?

Perplexity's citation cookbook separately collects search results and extracts the reference numbers used in the answer. Its reference-list example includes records whose identifiers appear in the text.

For a website citation report, the corresponding procedure records the answer's markers and their matched URLs separately from the complete returned result collection. A result's presence supplies a source record; the marker-to-ID match supplies the link associated with an answer reference.

The cookbook also recommends retaining an unmatched reference number without a link. It directs integrations to use returned source URLs and warns that URLs generated by the model can be hallucinated.

Related terms

• Perplexity
• AI citation
• Citation tracking
• How do I request inline citation markers from Perplexity's Agent API?

FAQ

Can I rely on markers appearing automatically?

Perplexity's Web Search documentation says their presence depends on the prompt. You can explicitly request bracketed inline markers, with one source per bracket, such as [1][2].

Does every preset use the same marker format?

The Streaming Citation Parsing guide gives [1] for fast and [web:1] for low. Your parser needs to handle the format used by the selected preset while preserving the identifier-to-URL mapping.

Sources

1. Perplexity, "Web Search", undated
2. Perplexity, "Give it tools", undated
3. Perplexity, "Streaming Citation Parsing", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer