> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truscan.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Results and ranking

> Filtering a query, reading a result, and the six signals behind every score.

## Request fields

`POST /api/search/query` accepts:

<ParamField body="query" type="string" required>
  The search query. Maximum 512 characters. `q` is accepted as an alias.
</ParamField>

<ParamField body="tier" type="string" default="instant">
  `instant`, `deep`, or `deep_reasoning`. See [Search tiers](/search/tiers).
</ParamField>

<ParamField body="limit" type="integer" default="10">
  Results to return. Values above 50 are clamped to 50.
</ParamField>

<ParamField body="enrich" type="boolean" default="true">
  Extract readable page content for each result. Set `false` to return links
  only and skip the per-page extraction cost.
</ParamField>

<ParamField body="format" type="string" default="json">
  `json`, `markdown`, or `text`. Non-JSON formats also populate `rendered`.
</ParamField>

<ParamField body="site" type="string">
  Restrict to a single domain, e.g. `arxiv.org`.
</ParamField>

<ParamField body="lang" type="string">
  Preferred result language.
</ParamField>

<ParamField body="freshness" type="string">
  `any`, `day`, `week`, `month`, or `year`.
</ParamField>

<ParamField body="category" type="string" default="general">
  `general`, `news`, `science`, `images`, `videos`, or `it`.
</ParamField>

The same search is available as `GET /api/search/query` using query parameters,
where `q` is required. Add `raw=1` with `format=markdown` or `format=text` to
get the rendered body directly as `text/markdown` or `text/plain` instead of JSON.

## A result

```json theme={null}
{
  "rank": 1,
  "url": "https://example.com/tls-13",
  "title": "What happens in a TLS 1.3 handshake?",
  "snippet": "TLS 1.3 reduces the handshake to a single round trip...",
  "domain": "example.com",
  "score": 0.91,
  "published_at": "2024-11-02T00:00:00Z",
  "components": {
    "consensus": 0.98,
    "position": 0.87,
    "lexical": 0.74,
    "proximity": 0.66,
    "authority": 0.81,
    "freshness": 0.40
  }
}
```

## The six ranking signals

`score` is a blend of the values in `components`. They are returned on every
result so you can audit a ranking, or re-rank it yourself.

| Signal      | Measures                                                   |
| ----------- | ---------------------------------------------------------- |
| `consensus` | How many independent sources returned this URL             |
| `position`  | How highly each engine placed it                           |
| `lexical`   | Query-term overlap with the title and snippet              |
| `proximity` | How close the query terms appear to one another            |
| `authority` | Domain-level reputation                                    |
| `freshness` | Recency, relative to the query's apparent time sensitivity |

<Tip>
  `consensus` is the strongest defence against a single engine's spam. If you
  re-rank, keep it weighted heavily.
</Tip>

## Stats

`stats` reports what the request actually did:

```json theme={null}
{
  "took_ms": 1180,
  "recall_ms": 420,
  "enrich_ms": 700,
  "candidates": 84,
  "deduped": 61,
  "enriched": 10,
  "cached": false
}
```

`cached: true` means the response was served from cache and **not billed**.

## Re-fetching a search

Every search has an `id`. Fetch it again without paying for a new one:

```bash theme={null}
curl https://api.truscan.co/api/search/searches/srch_abc123 \
  -H "Authorization: Bearer $TRUSCAN_API_KEY"
```