Results and ranking

Request fields

POST /api/search/query accepts:

string

required

The search query. Maximum 512 characters. q is accepted as an alias.

string

default:"instant"

instant, deep, or deep_reasoning. See Search tiers.

integer

default:"10"

Results to return. Values above 50 are clamped to 50.

boolean

default:"true"

Extract readable page content for each result. Set false to return links only and skip the per-page extraction cost.

string

default:"json"

json, markdown, or text. Non-JSON formats also populate rendered.

string

Restrict to a single domain, e.g. arxiv.org.

string

Preferred result language.

string

any, day, week, month, or year.

string

default:"general"

general, news, science, images, videos, or it.

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

{
  "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

consensus is the strongest defence against a single engine’s spam. If you re-rank, keep it weighted heavily.

Stats

stats reports what the request actually did:

{
  "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:

curl https://api.truscan.co/api/search/searches/srch_abc123 \
  -H "Authorization: Bearer $TRUSCAN_API_KEY"

Get started

Search

Webhooks

Billing

Reference

Results and ranking

Request fields

A result

The six ranking signals

Stats

Re-fetching a search

​Request fields

​A result

​The six ranking signals

​Stats

​Re-fetching a search

Request fields

A result

The six ranking signals

Stats

Re-fetching a search