Web Search

Perform AI-powered web searches with optional intelligent answers. The Search API supports batch processing of multiple queries and provides customizable search options for filtering and ranking results.

Overview

The search endpoint enables you to:

Execute multiple search queries in a single request
Get AI-generated answers based on search results
Filter results by date, domain, region, and more
Control result quality and relevance

Endpoint

POST /search

Authentication

Headers:
  X-Client-ID: your_client_id
  X-Client-Secret: your_client_secret
  Content-Type: application/json

Request Body

Field	Type	Required	Description
`queries`	string[]	Yes	Array of search queries
`options`	object	No	Additional search options

###options Object

Option	Type	Description
`includeAnswers`	boolean	No
`includeMetadata`	boolean	Include search metadata in response
`summaryLevel`	string	AI answer quality: 'low', 'medium', 'intelligent'
`maxResults`	number	Maximum results per query (default: 10)
`language`	string	Language code (e.g., 'en', 'es', 'fr')
`region`	string	Region code (e.g., 'us', 'uk', 'eu')
`freshness`	string	Result freshness: 'day', 'week', 'month', 'year', 'all'
`startDate`	string	Start date for filtering (ISO 8601)
`endDate`	string	End date for filtering (ISO 8601)
`includeDomains`	string[]	Only include these domains
`excludeDomains`	string[]	Exclude these domains
`searchTopic`	string	Topic: 'general', 'news', 'finance'
`searchDepth`	string	Depth: 'basic', 'advanced'

Response

Returns an array of search results, one per query:

[
  {
    success: boolean,
    query: string,
    results: Array<{
      url: string,
      title: string,
      content: string,
      ...
    }>,
    answer?: string,
    metadata?: object,
    time_took: number
  }
]

Examples

Basic Search

import { SearchClient } from 'search-agent';

const client = new SearchClient({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET
});

const results = await client.search(['TypeScript best practices']);

console.log(results[0].results);

const response = await fetch('https://api.oblien.com/search', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    queries: ['TypeScript best practices']
  })
});

const results = await response.json();
console.log(results[0].results);

curl -X POST https://api.oblien.com/search \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": ["TypeScript best practices"]
  }'

Response:

[
  {
    "success": true,
    "query": "TypeScript best practices",
    "results": [
      {
        "url": "https://example.com/typescript-guide",
        "title": "TypeScript Best Practices 2025",
        "content": "Learn the best practices for TypeScript development...",
        "snippet": "Top 10 TypeScript best practices every developer should know"
      }
    ],
    "time_took": 1542
  }
]

Search with AI Answers

const results = await client.search(
  ['What is machine learning?'],
  { summaryLevel: 'intelligent', includeAnswers: true }
);

console.log('Answer:', results[0].answer);
console.log('Sources:', results[0].results.length);

const response = await fetch('https://api.oblien.com/search', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    queries: ['What is machine learning?'],
    options: {
      includeAnswers: true,
      summaryLevel: 'intelligent'
    }
  })
});

const results = await response.json();
console.log('Answer:', results[0].answer);

curl -X POST https://api.oblien.com/search \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": ["What is machine learning?"],
    "options": {
      "includeAnswers": true,
      "summaryLevel": "intelligent"
    }
  }'

Response:

[
  {
    "success": true,
    "query": "What is machine learning?",
    "answer": "Machine learning is a subset of artificial intelligence that enables systems to learn and improve from experience without being explicitly programmed. It uses algorithms and statistical models to analyze patterns in data, make decisions, and predictions with minimal human intervention.",
    "results": [
      {
        "url": "https://example.com/ml-intro",
        "title": "Introduction to Machine Learning",
        "content": "Machine learning is transforming how we..."
      }
    ],
    "time_took": 2341
  }
]

Batch Search

const results = await client.search(
  [
    'Latest AI developments',
    'Neural network architectures',
    'Deep learning frameworks'
  ],
  {
    includeAnswers: true,
    summaryLevel: 'medium',
    maxResults: 5,
    freshness: 'month'
  }
);

results.forEach(result => {
  console.log(`Query: ${result.query}`);
  console.log(`Answer: ${result.answer}`);
  console.log(`Results: ${result.results.length}\n`);
});

const response = await fetch('https://api.oblien.com/search', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    queries: [
      'Latest AI developments',
      'Neural network architectures',
      'Deep learning frameworks'
    ],
    options: {
      includeAnswers: true,
      summaryLevel: 'medium',
      maxResults: 5,
      freshness: 'month'
    }
  })
});

const results = await response.json();

curl -X POST https://api.oblien.com/search \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      "Latest AI developments",
      "Neural network architectures",
      "Deep learning frameworks"
    ],
    "options": {
      "includeAnswers": true,
      "summaryLevel": "medium",
      "maxResults": 5,
      "freshness": "month"
    }
  }'

Advanced Filtering

const results = await client.search(
  ['climate change research'],
  {
    includeAnswers: true,
    includeDomains: ['nature.com', 'science.org', 'pnas.org'],
    freshness: 'year',
    maxResults: 10,
    language: 'en',
    region: 'us',
    searchTopic: 'general',
    includeMetadata: true
  }
);

const response = await fetch('https://api.oblien.com/search', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    queries: ['climate change research'],
    options: {
      includeAnswers: false,
      includeDomains: ['nature.com', 'science.org', 'pnas.org'],
      freshness: 'year',
      maxResults: 10,
      language: 'en',
      region: 'us',
      searchTopic: 'general',
      includeMetadata: true
    }
  })
});

curl -X POST https://api.oblien.com/search \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": ["climate change research"],
    "options": {
      "includeAnswers": false,
      "includeDomains": ["nature.com", "science.org", "pnas.org"],
      "freshness": "year",
      "maxResults": 10,
      "language": "en",
      "region": "us",
      "searchTopic": "general",
      "includeMetadata": true
    }
  }'

Date Range Search

const results = await client.search(
  ['tech industry news'],
  {
    includeAnswers: true,
    startDate: '2025-01-01',
    endDate: '2025-01-31',
    searchTopic: 'news',
    summaryLevel: 'medium'
  }
);

const response = await fetch('https://api.oblien.com/search', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    queries: ['tech industry news'],
    options: {
      includeAnswers: true,
      startDate: '2025-01-01',
      endDate: '2025-01-31',
      searchTopic: 'news',
      summaryLevel: 'medium'
    }
  })
});

curl -X POST https://api.oblien.com/search \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": ["tech industry news"],
    "options": {
      "includeAnswers": true,
      "startDate": "2025-01-01",
      "endDate": "2025-01-31",
      "searchTopic": "news",
      "summaryLevel": "medium"
    }
  }'

Summary Levels

Choose the right summary level for your use case:

Level	Speed	Quality	Use Case
low	Fastest (< 1s)	Basic	Quick facts, simple queries
medium	Medium (1-2s)	Balanced	General use, most queries
intelligent	Slower (2-4s)	Highest	Complex topics, detailed analysis

Error Handling

try {
  const results = await client.search(['test query']);
  console.log(results);
} catch (error) {
  console.error('Search failed:', error.message);
}

const response = await fetch('https://api.oblien.com/search', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    queries: ['test query']
  })
});

const results = await response.json();
if (!results[0].success) {
  console.error('Search failed:', results[0].error);
}

# Error responses return HTTP 400/500 with error details
curl -X POST https://api.oblien.com/search \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"queries": []}'

# Response:
# {"success": false, "error": "Queries are required"}

Best Practices

Batch related queries - Process multiple related searches in one request for better performance
Use appropriate summary levels - Choose 'low' for speed, 'intelligent' for quality
Set reasonable maxResults - Typical range is 5-20 results per query
Apply domain filters - Use includeDomains/excludeDomains for more relevant results
Use freshness wisely - Filter by date range for time-sensitive queries
Handle errors gracefully - Always check success status and handle failures

Rate Limits

100 requests per minute per client
Maximum 10 queries per request
Results capped at 100 per query

Next Steps

Learn about Content Extraction for extracting specific data from pages
Explore Deep Research for comprehensive website analysis

On this page