Pagination and Filters

The Search API provides pagination and optional filters that you can include in the search request.

You can use page to request a specific result page and use locale, safe, and time_range to configure the search request.

Pagination

Use the page parameter to specify which result page to fetch.

The OpenAPI defines the following limits:

• Minimum: 1
• Maximum: 20
• Default: 1

For example, to request the second result page:

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

The page value must be an integer between 1 and 20.

Request a Specific Page

You can request any page from 1 through 20.

curl -X POST "YOUR_SCRAPER_API_URL/v1/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "web scraping best practice",
    "page": 2
  }'

The returned page field identifies the result page that was returned.

Locale

Use the locale parameter to specify the locale for the search.

The OpenAPI accepts:

• A language code, such as en
• A language-region tag, such as en-US
• all

For example:

{
  "query": "web scraping",
  "locale": "en-US"
}

The locale parameter is optional.

Safe Search

Use the safe parameter to specify the safe-search level.

The supported values are:

The default value is off.

Example

{
  "query": "web scraping",
  "safe": "moderate"
}

Only off, moderate, and strict are accepted values for this parameter.

Time Range

Use the time_range parameter to restrict results to a recency window.

The supported values are:

For example:

{
  "query": "web scraping",
  "time_range": "week"
}

The time_range parameter is optional.

Combining Parameters

You can include multiple optional parameters in the same Search request.

For example:

{
  "query": "web scraping best practice",
  "locale": "en-US",
  "page": 2,
  "safe": "moderate",
  "time_range": "month"
}

This request uses:

• locale to specify en-US
• page to request page 2
• safe with the moderate value
• time_range with the month value

All four parameters are defined as optional in the SearchRequest schema.

Complete Request

The following example combines all available Search request options:

curl -X POST "YOUR_SCRAPER_API_URL/v1/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "web scraping best practice",
    "locale": "en-US",
    "page": 2,
    "safe": "moderate",
    "time_range": "month"
  }'

Parameter Summary

These are the request parameters defined by the current SearchRequest schema.

What's Next?

You now know how to paginate Search results and configure the available Search filters.

Continue with Search Jobs to learn how to list and retrieve search jobs.