Search Workflows

The Search API lets you submit a search query and receive search results. Each search returns a unique job_id, which can be used to retrieve the full details of a completed search job.

Complete Search Workflow

The following diagram shows how the Search API endpoints work together.

A search starts with a query and returns search results together with a unique job ID.

Typical Workflow

Most applications follow these steps when working with Search.

Step 1 — Submit a Search

Start by submitting a search query.

POST /v1/search

The request requires a query field.

{
  "query": "web scraping"
}

You can also provide optional search settings such as:

• locale
• page
• safe
• time_range

The query can contain between 1 and 1,000 characters. The available values and limits for the optional fields are covered in Search Parameters.

Step 2 — Receive the Search Response

A successful search returns a SearchResponse.

The response includes:

• job_id
• query
• page
• attempts
• results
• suggestions
• spelling_correction

The job_id uniquely identifies the search job.

Step 3 — Review the Results

The results array contains the search results returned for the requested page.

Each result contains:

• position
• title
• url

It can also include:

• snippet
• thumbnail
• displayed_url
• source_host

The position field represents the 1-based rank of the result on the page.

Finding Previous Search Jobs

Search responses include a job_id that identifies the search.

You can list search jobs for the authenticated user using:

GET /v1/search/jobs

The Search Jobs endpoint supports optional filters for:

• Search query
• Job status
• Start date
• End date
• Page
• Page size

The page_size can be between 1 and 100 and defaults to 10.

Retrieving Search Job Details

After you have a search job_id, retrieve the full details of a completed search job using:

GET /v1/search/{job_id}

The response provides the search configuration and its results.

It can include:

• job_id
• query
• locale
• page
• safe
• time_range
• status
• results
• results_count
• suggestions
• spelling_correction
• attempts
• final_url
• duration_ms
• tokens_charged
• block_reason
• error_code
• error_message
• created_at
• completed_at

The endpoint description specifically defines this operation as retrieving the full details and results for a completed search job.

Pagination

The Search API supports result pagination through the page request parameter.

The page number must be between 1 and 20.

For example:

{
  "query": "web scraping",
  "page": 2
}

The response returns the page that was requested in the page field.

Search Options

The Search API provides additional request options for controlling the search.

Locale

Use locale to specify a language code, language-region tag, or all.

Examples supported by the OpenAPI schema include:

en
en-US
all

Safe Search

Use safe to select a safe-search level.

Supported values are:

off
moderate
strict

The default is off.

Time Range

Use time_range to restrict results to a recency window.

Supported values are:

day
week
month
year

Result Page

Use page to request a specific result page from 1 through 20.

These options can be combined with the required query field in the same request.

Common Workflow Patterns

Standard Search

This is the basic Search workflow.

Search with Pagination

Use the page parameter when you need to retrieve another result page.

Find and Retrieve a Previous Search

Use this workflow when you need to find a previous search job and retrieve its details.

Best Practices

• Store the job_id returned by the Search API if you need to retrieve the search later.
• Use page to request additional result pages.
• Use locale when you need to specify the search locale.
• Use safe when you need a specific safe-search level.
• Use time_range when you need to restrict results to a specific recency window.
• Use the Search Jobs endpoint when you need to find previous search jobs.
• Use the Search Job Details endpoint to retrieve the full details and results of a completed search job.

Next Steps

You now understand the main Search API workflow.

Continue with:

• Getting Started — Make your first Search API request.