Skip to content

API reference

Search with typed filters and result projection

POST /v1/search

Returns ranked web results using the shared typed filter and projection contract.

Authentication
Send an API key or a service-account access token as a Bearer token.
Billing
Billing or an account spend limit can reject this request with 402.
Rate limits
A 429 response carries Retry-After; wait that long, then retry with backoff.

Request body

Write a search request, send it and read the results.

This is a real request. Normal billing, spend limits, and rate limits apply.

SearchPostRequest

Public POST search request.

  • filter string | null Optional

    An expression in the filter language that every result must satisfy.

    Minimum length
    • 1
    Maximum length
    • 65536
  • lang string | null Optional

    A two-letter lowercase language code that results must match.

    Pattern
    • ^[a-z]{2}$
  • limit integer | null Optional

    The maximum number of results. The default is 20.

    Minimum
    • 1
    Maximum
    • 50
  • max_results_per_domain integer | null Optional

    The maximum number of results from one registrable domain.

    Minimum
    • 1
    Maximum
    • 10
  • query string Required

    The search text.

    Minimum length
    • 1
    Maximum length
    • 512
  • ranking null | SearchRanking Optional
  • select SearchResultField[] Optional

    The fields each result returns.

    Minimum items
    • 1

Responses

  • 200

    Ranked projected search results

    SearchPostResponse X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-ResetX-Request-ID
  • 400

    The request violated the public contract

    SearchV1Error X-Request-ID
  • 401

    A valid API key is required

    SearchV1Error X-Request-ID
  • 402

    Billing or a spend limit rejected execution

    SearchV1Error X-Request-ID
  • 403

    The API key lacks search permission

    SearchV1Error X-Request-ID
  • 429

    A rate limit rejected execution

    SearchV1Error Retry-AfterX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-ResetX-Request-ID
  • 502

    The search request could not be completed

    SearchV1Error X-Request-ID
  • 503

    Search is temporarily unavailable

    SearchV1Error X-Request-ID
Response 200 
{
  "duration_ms": 0,
  "request_id": "string",
  "results": [
    {
      "fields": {},
      "rank": 1
    }
  ],
  "select": [
    "url"
  ]
}

SearchPostResponse

Public POST search response.

  • duration_ms integer Required

    The time taken to answer, in milliseconds.

    Minimum
    • 0
  • request_id string Required

    The reference of the request, to quote when contacting support.

  • results ProjectedPageResult[] Required

    The results, best first.

  • select SearchResultField[] Required

    The fields each result returns, after the default is applied.

Schemas

ErrorCode

Machine-readable product API failure.

Allowed values
  • unauthenticated
  • forbidden
  • invalid_request
  • not_found
  • conflict
  • payment_required
  • too_many_requests
  • upstream
  • internal

ErrorRecovery

Browser-safe recovery action selected by the authoritative product boundary.

ErrorRecovery alternatives
VariantType
1object
2object

PageResultFields

Optional nullable projected fields. Each property is omitted when not selected, `null` when selected but unavailable, or carries its typed value.

  • anchor null | string Optional

    Aggregated inbound anchor text.

  • author null | string Optional

    Page author.

  • categories null | object[] Optional

    Scored taxonomy categories.

  • content_angle null | string Optional

    Classified content angle.

  • description null | string Optional

    Result description.

  • document_intent null | string Optional

    Classified document intent.

  • domain null | string Optional

    Registrable or host domain.

  • domain_refdomains null | integer Optional

    Domain referring-domain count.

  • first_seen null | string Optional

    First-seen timestamp.

  • highlights null | string[] Optional

    Up to three query-relevant passages.

  • language null | string Optional

    Document language.

  • location null | string Optional

    Geographic location code.

  • page_type null | string Optional

    Page content type.

  • publish_time null | string Optional

    Published timestamp.

  • refdomains null | integer Optional

    Referring-domain count.

  • republished null | boolean Optional

    Whether the document was republished.

  • rule_type null | string Optional

    Applied rule type.

  • site_name null | string Optional

    Site display name.

  • title null | string Optional

    Page title.

  • url null | string Optional

    Canonical page URL.

  • word_count null | integer Optional

    Visible word count.

ProjectedPageResult

One ranked projected result.

  • fields PageResultFields Required

    Exactly the requested fields.

  • rank integer Required

    One-based result rank.

    Minimum
    • 1

SearchRanking

What the results should prioritize.

Allowed values
  • precision
  • balanced
  • authority
  • content_gap

SearchResultField

Public fields that may be selected in a search response.

Allowed values
  • url
  • title
  • description
  • anchor
  • site_name
  • author
  • language
  • domain
  • categories
  • location
  • page_type
  • publish_time
  • first_seen
  • refdomains
  • domain_refdomains
  • word_count
  • rule_type
  • document_intent
  • content_angle
  • republished
  • highlights

SearchV1Error

Search v1's original closed error envelope.

  • code ErrorCode Required

    Closed status category.

    Allowed
    • unauthenticated
    • forbidden
    • invalid_request
    • not_found
    • conflict
    • payment_required
    • too_many_requests
    • upstream
    • internal
  • message string Required

    Safe operator diagnostic.

  • reason SearchV1ErrorReason Required

    Closed Search v1 reason.

    Allowed
    • malformed_request
    • authentication_required
    • permission_denied
    • api_key_name_invalid
    • spend_policy_invalid
    • rate_policy_invalid
    • resource_not_found
    • state_conflict
    • insufficient_funds
    • spend_limit_exceeded
    • rate_limit_exceeded
    • dependency_unavailable
    • internal_failure
  • recovery null | ErrorRecovery Optional
  • request_id string | null Optional

    The request reference, equal to the response's `X-Request-ID`; quote it to support.

  • validation null | ValidationReport Optional

SearchV1ErrorReason

Closed failure-reason vocabulary retained for the published Search v1 contract.

Allowed values
  • malformed_request
  • authentication_required
  • permission_denied
  • api_key_name_invalid
  • spend_policy_invalid
  • rate_policy_invalid
  • resource_not_found
  • state_conflict
  • insufficient_funds
  • spend_limit_exceeded
  • rate_limit_exceeded
  • dependency_unavailable
  • internal_failure

ValidationIssue

One actionable, privacy-safe contract violation.

  • allowed_values array | null Optional
    Maximum items
    • 16
  • code string Required

    Stable, extensible machine-readable category.

    Maximum length
    • 64
  • path string Required

    RFC 6901 pointer to the rejected location; empty means the root value.

    Maximum length
    • 1024
  • suggestion string Required

    Code-owned instruction for correcting the request.

    Maximum length
    • 512

ValidationReport

Bounded validation feedback shared by model, REST, and MCP boundaries.

  • contract string Required

    Stable contract name, normally the published schema component name.

    Maximum length
    • 128
  • issues ValidationIssue[] Required

    At most eight deterministic violations. Correct every issue before retrying.

    Maximum items
    • 8
  • truncated boolean Required

    Whether more violations were omitted; retry after correcting the listed issues.

Commands

No matching commands

Confirm it's you