POST
/
api
/
web
Web Search
curl --request POST \
  --url https://nano-gpt.com/api/web \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{
  "query": "<string>",
  "depth": "<string>",
  "outputType": "<string>",
  "structuredOutputSchema": "<string>",
  "includeImages": true,
  "fromDate": "<string>",
  "toDate": "<string>",
  "excludeDomains": [
    "<string>"
  ],
  "includeDomains": [
    "<string>"
  ]
}'
{
  "error": "Query parameter is required and must be a string"
}

​
Overview

The Web Search API allows you to perform AI-powered web searches using Linkup, returning up-to-date information from across the internet. This API supports multiple output formats, date filtering, domain filtering, and two search depth options.

​
Authentication

​
x-api-key
string
required
Your NanoGPT API key
Alternatively, you can use Bearer token authentication:
​
Authorization
string
Bearer YOUR_API_KEY

​
Request Body

​
query
string
required
The search query to send to Linkup
​
depth
string
default:"standard"
Search depth. Options: “standard” or “deep”
  • standard: $0.006 per search
  • deep: $0.06 per search
​
outputType
string
default:"searchResults"
Output format. Options: “searchResults”, “sourcedAnswer”, or “structured”
​
structuredOutputSchema
string
Required when outputType is “structured”. JSON schema string defining the desired response format
​
includeImages
boolean
default:false
Whether to include image results in the search
​
fromDate
string
Filter results from this date (YYYY-MM-DD format)
​
toDate
string
Filter results until this date (YYYY-MM-DD format)
​
excludeDomains
string[]
Array of domains to exclude from search results
​
includeDomains
string[]
Array of domains to search exclusively

​
Response

​
data
object|array
Search results, answer, or structured data depending on outputType
​
metadata
object

​
Output Formats

​
Search Results (default)

Returns an array of search results with text and image entries: 
{
  "data": [
    {
      "type": "text",
      "title": "Article Title",
      "url": "https://example.com/article",
      "content": "Article content snippet..."
    },
    {
      "type": "image",
      "title": "Image Title",
      "url": "https://example.com/image.jpg",
      "imageUrl": "https://example.com/image.jpg"
    }
  ],
  "metadata": {
    "query": "your search query",
    "depth": "standard",
    "outputType": "searchResults",
    "timestamp": "2025-07-08T09:00:00.000Z",
    "cost": 0.006
  }
}

​
Sourced Answer

Returns a comprehensive answer with source citations: 
{
  "data": {
    "answer": "The comprehensive answer to your query...",
    "sources": [
      {
        "name": "Source Name",
        "url": "https://example.com",
        "snippet": "Relevant snippet from the source..."
      }
    ]
  },
  "metadata": {
    "query": "your search query",
    "depth": "standard",
    "outputType": "sourcedAnswer",
    "timestamp": "2025-07-08T09:00:00.000Z",
    "cost": 0.006
  }
}

​
Structured Output

Returns data matching your provided JSON schema: 
{
  "data": {
    // Your structured data according to the schema
  },
  "metadata": {
    "query": "your search query",
    "depth": "standard",
    "outputType": "structured",
    "timestamp": "2025-07-08T09:00:00.000Z",
    "cost": 0.006
  }
}

​
Examples

import requests
import json

# Your API key
api_key = "YOUR_API_KEY"

# API endpoint
url = "https://nano-gpt.com/api/web"

# Headers
headers = {
    "Content-Type": "application/json",
    "x-api-key": api_key
}

# Basic search
basic_search = {
    "query": "artificial intelligence trends 2025"
}

response = requests.post(url, headers=headers, json=basic_search)
results = response.json()

# Print results
if results["metadata"]["outputType"] == "searchResults":
    for result in results["data"]:
        print(f"Title: {result['title']}")
        print(f"URL: {result['url']}")
        print(f"Content: {result.get('content', 'N/A')[:200]}...")
        print("-" * 50)
    print(f"Search cost: ${results['metadata']['cost']}")

​
Advanced Examples

​
Deep Search with Date Filtering

def deep_search_with_dates(query, from_date, to_date):
    data = {
        "query": query,
        "depth": "deep",
        "fromDate": from_date,
        "toDate": to_date
    }
    
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# Search for recent research
results = deep_search_with_dates(
    "quantum computing breakthroughs",
    "2025-01-01",
    "2025-07-01"
)

​
Structured Output for Data Extraction

def extract_structured_data(query, schema):
    data = {
        "query": query,
        "outputType": "structured",
        "structuredOutputSchema": json.dumps(schema)
    }
    
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# Define schema for extracting programming language data
schema = {
    "type": "object",
    "properties": {
        "languages": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "rank": {"type": "number"},
                    "name": {"type": "string"},
                    "popularityScore": {"type": "string"},
                    "primaryUseCase": {"type": "string"}
                }
            }
        }
    }
}

# Extract structured data
results = extract_structured_data(
    "top 5 programming languages 2025",
    schema
)

def search_specific_domains(query, domains, exclude=False):
    data = {
        "query": query,
        "outputType": "sourcedAnswer"
    }
    
    if exclude:
        data["excludeDomains"] = domains
    else:
        data["includeDomains"] = domains
    
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# Search only trusted news sources
news_results = search_specific_domains(
    "latest tech acquisitions",
    ["reuters.com", "bloomberg.com", "techcrunch.com"],
    exclude=False
)

# Exclude certain domains
filtered_results = search_specific_domains(
    "python tutorials",
    ["w3schools.com", "geeksforgeeks.org"],
    exclude=True
)

​
Error Handling

{
  "error": "Query parameter is required and must be a string"
}

​
Rate Limiting

The API is rate-limited to 10 requests per minute per IP address. If you exceed this limit, you’ll receive a 429 status code.

​
Best Practices

  1. Use Standard Search for General Queries: Standard search is 10x cheaper and sufficient for most use cases.
  2. Use Deep Search for Research: Deep search provides more comprehensive results and is ideal for research tasks or when you need extensive information.
  3. Leverage Domain Filtering: Use includeDomains to search specific trusted sources or excludeDomains to filter out unwanted sources.
  4. Date Filtering for Current Events: Use fromDate and toDate to get the most recent information on rapidly evolving topics.
  5. Structured Output for Data Extraction: Use structured output when you need to extract specific data points from search results in a predictable format.
  6. Handle Errors Gracefully: Always implement error handling for rate limits, insufficient balance, and network errors.
  7. Cache Results: Consider caching search results for identical queries to reduce costs and improve performance.

​
Output Type Selection Guide

  • searchResults: Best for general searches where you want to see multiple sources and snippets. Ideal for research and exploration.
  • sourcedAnswer: Best when you want a comprehensive answer synthesized from multiple sources. Great for factual questions and summaries.
  • structured: Best when you need to extract specific data points in a predictable format. Perfect for data collection and automation.

​
Pricing

  • Standard Search: $0.006 per search
  • Deep Search: $0.06 per search
A minimum balance of $1.00 is required to use the web search API.