titan_search

Use titan_search when your agent has a question but not the URLs. It returns metadata-only organic results—ranked URLs, titles, and snippets. To read the pages, follow up with titan_fetch. Required scope: mcp:search

Parameters

string

required

The search query. Raw search operators you type here ("exact phrase", -excluded, OR) are passed through to the provider.

string

Identifier of the search platform to query. Call titan_list_templates with action_type: "search" to see the platforms available to your account. Defaults to the platform default when omitted.Selection is explicit—there is no automatic fallback to a different platform if one fails.

integer

default:"10"

Results to return, up to 100. Requesting more than you will read wastes time, not credits: search bills per run, not per result.

string

default:"raw_and_structured"

How to combine query with the structured fields below.

raw — send query untouched, ignore structured fields
structured — build the query from structured fields only
raw_and_structured — combine both

string[]

Restrict results to these domains. Compiles to site: operators.

string[]

Remove these domains from results. Compiles to -site: operators.

string[]

Restrict to file extensions, for example ["pdf"]. Compiles to filetype:.

string[]

Require terms in the page title. Compiles to intitle:.

string[]

Require terms in the URL. Compiles to inurl:.

string

Two-letter country code for regional results, for example us or de.

string

Language code for results, for example en or fr.

string

Recency filter: any, day, week, month, or year.

boolean

default:"true"

Wait for results inside the call. Set false to receive a run_id immediately.

integer

default:"30"

Seconds to wait, capped at 30.

string

Deduplicate repeated calls for 24 hours. See Idempotency and retries.

Operator support

Search platforms differ in which operators they accept. Unsupported fields are dropped, not rejected—your search still runs, and each dropped field is reported in warnings with code operator_unsupported naming exactly what was removed. Quoted phrases, -term exclusions, OR alternation, include_domains, and exclude_domains work everywhere. Support for file_types, title_terms, url_terms, country, language, and freshness varies.

If your query depends on a specific operator, run it once and check warnings. An empty warnings array means every field you sent was applied.

Example

Find recent PDFs on a specific domain:

{
  "query": "annual report",
  "search_provider": "brave",
  "max_results": 10,
  "include_domains": ["sec.gov"],
  "file_types": ["pdf"],
  "freshness": "year"
}

Response

{
  "run_id": "9f1c2e84-5b3a-4d7e-8c19-2a6f0b4d7e31",
  "status": "completed",
  "results": [
    {
      "url": "https://www.sec.gov/files/annual-report-2026.pdf",
      "final_url": "https://www.sec.gov/files/annual-report-2026.pdf",
      "display_url": "sec.gov › files",
      "title": "Annual Report 2026",
      "snippet": "The agency's fiscal year results and outlook...",
      "rank": 1,
      "source": "brave",
      "search_provider": "brave",
      "target_platform": "brave",
      "query": "annual report filetype:pdf site:sec.gov",
      "result_type": "organic",
      "retrieved_at": "2026-07-27T09:14:22Z",
      "metadata": {}
    }
  ],
  "usage": {
    "backend_execution_id": "9f1c2e84-5b3a-4d7e-8c19-2a6f0b4d7e31",
    "billing_unit": "successful_delivery",
    "records_returned": 10,
    "records_available": 10,
    "credits_estimated": 1,
    "billing_status": "billable"
  },
  "warnings": [],
  "request_id": "req_8f3a1c9e2b7d4056"
}

Result fields

Field	Meaning
`url`	The result URL
`final_url`	Canonical URL after redirects, when different
`display_url`	Breadcrumb-style URL as the provider displays it
`title`	Result title
`snippet`	Provider-supplied summary text
`rank`	Position in the result list, starting at 1
`search_provider`	Provider that returned it
`query`	The compiled query actually sent, after operator expansion
`result_type`	`organic` or `ad`
`retrieved_at`	RFC 3339 timestamp
`metadata`	Provider-specific extras

Inspect query in the response to see exactly how your structured fields compiled. That is the fastest way to debug a search that returned nothing useful.

Credits

One credit per search run, regardless of how many results you request. A search that completes and confidently returns zero organic results is still billable—it delivered a valid answer. A search that is blocked, rate-limited, or times out with no records is not billed. See Credits and usage.

Warnings you may see

Code	Meaning
`operator_unsupported`	A field was dropped for this provider; the search still ran
`provider_no_results`	The search completed with zero organic results
`next_step`	The run outlived the wait window; call `titan_get_run`

Common patterns

Narrow to a source you trust

{ "query": "changelog", "include_domains": ["kubernetes.io"], "freshness": "month" }

Exclude noise

{ "query": "postgres tuning", "exclude_domains": ["pinterest.com", "quora.com"] }

Find documents, not pages

{ "query": "security whitepaper", "file_types": ["pdf"], "search_provider": "brave" }

Next steps

titan_fetch — read the pages you discovered
Research agent example — search and fetch as one pipeline
Errors and warnings

Get started

Tool reference

How it works

Integration examples

Parameters

Operator support

Example

Response

Result fields

Credits

Warnings you may see

Common patterns

Next steps

​Parameters

​Operator support

​Example

​Response

​Result fields

​Credits

​Warnings you may see

​Common patterns

​Next steps

Parameters

Operator support

Example

Response

Result fields

Credits

Warnings you may see

Common patterns

Next steps