Skip to content

Search API

Filters and fields

Narrow a POST search with the filter language and choose the fields each result returns.

POST /api/v1/search takes the query with a filter, a field projection and a language. Every value is checked against the public contract; a rejected request returns 400 and names the fields to correct.

Request body 
{
  "query": "semiconductor export controls",
  "limit": 20,
  "lang": "en",
  "filter": "(@categories INCLUDES ANY [\"/News\"] AND @publish_time >= now-1d)",
  "select": [
    "url",
    "title",
    "publish_time",
    "highlights"
  ]
}

Request fields

  • query string Required

    The search text.

    Minimum length
    • 1
    Maximum length
    • 512
  • limit integer | null Optional

    The maximum number of results. The default is 20.

    Minimum
    • 1
    Maximum
    • 50
  • lang string | null Optional

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

    Pattern
    • ^[a-z]{2}$
  • filter string | null Optional

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

    Minimum length
    • 1
    Maximum length
    • 65536
  • select SearchResultField[] Optional

    The fields each result returns.

    Minimum items
    • 1

Filter language

A filter is one or more predicates joined with AND and OR, grouped in parentheses. A predicate names a field with @, then an operator, then a value: a double-quoted string, a number, true or false, or a JSON list. A filter holds at most 50 predicates, 50 values in one list and three levels of parentheses.

Filters 
@domain IN ["python.org", "mozilla.org"]
@categories INCLUDES NONE ["/Adult"]
(@categories INCLUDES ANY ["/News"] AND @publish_time >= now-1d)
@page_type = "Article" AND @word_count >= 800
@language = "de" OR @location = "DE"
@title : "benchmark" AND @url ^ "https://docs."

Each field takes the operators of its value kind. A time compares with now-5m, now-2h, now-1d or now-1w, or with a quoted ISO 8601 date such as "2025-01-01". A list value is a JSON array.

Filter operators by field kind
KindFieldsOperators
Texttitle, description, url, content: !: PHRASE NOT PHRASE
Keywordsite_name, author, domain, page_type, rule_type, document_intent, content_angle= != IN NOT IN : !: ^ !^
Codelanguage, location= != IN NOT IN
Numberword_count= != < <= > >= BETWEEN
Timepublish_time, first_seen= != < <= > >= BETWEEN
ListcategoriesINCLUDES ANY INCLUDES ALL INCLUDES NONE
Flagrepublished= !=

Result fields

select names the fields of every result. Omit it to receive url, title, description and language. A selected field that a page does not have is null. The content field can be filtered on but not selected.

  • url null | string Optional

    Canonical page URL.

  • title null | string Optional

    Page title.

  • description null | string Optional

    Result description.

  • anchor null | string Optional

    Aggregated inbound anchor text.

  • site_name null | string Optional

    Site display name.

  • author null | string Optional

    Page author.

  • language null | string Optional

    Document language.

  • domain null | string Optional

    Registrable or host domain.

  • categories null | object[] Optional

    Scored taxonomy categories.

  • location null | string Optional

    Geographic location code.

  • page_type null | string Optional

    Page content type.

  • publish_time null | string Optional

    Published timestamp.

  • first_seen null | string Optional

    First-seen timestamp.

  • refdomains null | integer Optional

    Referring-domain count.

  • domain_refdomains null | integer Optional

    Domain referring-domain count.

  • word_count null | integer Optional

    Visible word count.

  • rule_type null | string Optional

    Applied rule type.

  • document_intent null | string Optional

    Classified document intent.

  • content_angle null | string Optional

    Classified content angle.

  • republished null | boolean Optional

    Whether the document was republished.

  • highlights null | string[] Optional

    Up to three query-relevant passages.

Page types

The page_type field takes one of these values:

Allowed values
  • Listing
  • Listing_Collection
  • Article
  • Landing_Page
  • Interactive_Tools
  • Image
  • Video
  • Audio
  • Document
  • User_Generated_Content
  • Core_Page

Commands

No matching commands

Confirm it's you