Search API

Search the web programmatically and get structured results with content extraction.

The Search API allows you to search the web programmatically and get structured results. Each result includes the page content extracted in your preferred format. Control results with geographic targeting, time filters, and per-result scrape options.

Endpoint

POST https://api.octivas.com/api/v1/search

Request Parameters

Core Parameters

Parameter	Type	Required	Default	Description
`query`	`string`	Yes	—	Search query (1–500 characters). Supports operators like `""` (exact match), `-` (exclude), `site:`, `filetype:`.
`limit`	`integer`	No	`5`	Maximum number of results (1–20)
`formats`	`string[]`	No	`["markdown"]`	Output formats for scraped content (see Output Formats)

Search Control

Parameter	Type	Required	Default	Description
`location`	`string`	No	—	Geographic location for geo-targeted results (e.g. `"San Francisco,California,United States"`, `"Germany"`)
`country`	`string`	No	—	ISO 3166-1 alpha-2 country code (e.g. `"US"`, `"DE"`, `"JP"`, `"BR"`)
`tbs`	`string`	No	—	Time-based search filter: `qdr:h` (past hour), `qdr:d` (past day), `qdr:w` (past week), `qdr:m` (past month), `qdr:y` (past year)

Per-Result Scrape Options

Parameter	Type	Required	Default	Description
`only_main_content`	`boolean`	No	—	Extract only the primary content of each result page, excluding navigation, sidebars, footers, etc.
`timeout`	`integer`	No	—	Request timeout in milliseconds (1,000–300,000)

Output Formats

The formats array accepts any combination of:

Format	Description
`markdown`	Page content converted to Markdown
`html`	Cleaned HTML content
`rawHtml`	Original unprocessed HTML
`screenshot`	Screenshot of the page (returned as a URL)
`links`	List of URLs found on the page
`json`	Structured data extraction
`images`	List of image URLs found on the page
`summary`	AI-generated summary of the page content

Example Request

curl -X POST https://api.octivas.com/api/v1/search \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "machine learning tutorials",
    "limit": 5,
    "formats": ["markdown"]
  }'

import Octivas from 'octivas';

const client = new Octivas('your_api_key');

const results = await client.search({
  query: 'machine learning tutorials',
  numResults: 5,
  extractContent: true
});

results.results.forEach(result => {
  console.log(result.title);
  console.log(result.url);
  console.log(result.markdown);
});

import octivas

client = octivas.Client("your_api_key")

results = client.search(
    query="machine learning tutorials",
    limit=5
)

for result in results.results:
    print(result.title)
    print(result.url)
    print(result.markdown)

Advanced Example

Use location targeting, time filters, and content options to refine your search:

curl -X POST https://api.octivas.com/api/v1/search \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best web scraping tools 2025",
    "limit": 10,
    "formats": ["markdown", "links"],
    "country": "US",
    "tbs": "qdr:m",
    "only_main_content": true,
    "timeout": 60000
  }'

const response = await fetch("https://api.octivas.com/api/v1/search", {
  method: "POST",
  headers: {
    "Authorization": "Bearer your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "best web scraping tools 2025",
    limit: 10,
    formats: ["markdown", "links"],
    country: "US",
    tbs: "qdr:m",
    only_main_content: true,
    timeout: 60000,
  }),
});

const result = await response.json();
console.log(`Found ${result.results_count} results`);

import requests

response = requests.post(
    "https://api.octivas.com/api/v1/search",
    headers={
        "Authorization": "Bearer your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "query": "best web scraping tools 2025",
        "limit": 10,
        "formats": ["markdown", "links"],
        "country": "US",
        "tbs": "qdr:m",
        "only_main_content": True,
        "timeout": 60000,
    },
)

result = response.json()
print(f"Found {result['results_count']} results")

Response

{
  "success": true,
  "query": "machine learning tutorials",
  "results_count": 3,
  "credits_used": 5,
  "results": [
    {
      "url": "https://example.com/ml-guide",
      "title": "Complete Machine Learning Guide",
      "description": "A comprehensive guide to machine learning concepts and tools.",
      "markdown": "# Machine Learning Guide\n\nThis comprehensive guide...",
      "html": "<h1>Machine Learning Guide</h1><p>This comprehensive guide...</p>",
      "links": [
        "https://example.com/ml-basics",
        "https://example.com/ml-advanced"
      ]
    },
    {
      "url": "https://example.com/ml-basics",
      "title": "ML Basics for Beginners",
      "description": "Learn the fundamentals of machine learning.",
      "markdown": "# ML Basics\n\nLearn the fundamentals..."
    }
  ]
}

Response Fields

Field	Type	Description
`success`	`boolean`	Whether the request succeeded
`query`	`string`	The search query used
`results_count`	`integer`	Number of results returned
`credits_used`	`integer`	Total credits consumed
`results`	`array`	Array of search result objects
`results[].url`	`string`	URL of the result page
`results[].title`	`string \| null`	Page title
`results[].description`	`string \| null`	Page meta description or search snippet
`results[].markdown`	`string \| null`	Page content as Markdown (if requested)
`results[].html`	`string \| null`	Page content as HTML (if requested)
`results[].raw_html`	`string \| null`	Original unprocessed HTML (if requested)
`results[].screenshot`	`string \| null`	Screenshot URL (if requested)
`results[].links`	`string[] \| null`	URLs found on the page (if requested)
`results[].images`	`string[] \| null`	Image URLs found on the page (if requested)
`results[].summary`	`string \| null`	AI-generated page summary (if requested)

On this page