AI Research Agent

Autonomous AI agent that searches the web, reads pages, and returns structured data matching your custom schema. Give it a research task and a JSON Schema — it decides which tools to use, gathers information across multiple steps, and returns clean structured output.

[!NOTE] See the API Guide for the shared request lifecycle (sync, async polling, async webhook), error envelope, rate limits, custom_vars, and deduplication. This page documents only the fields and behaviour unique to this endpoint.

Try it

Pricing

Endpoint

Input Parameters

Schema Format

The schema field must be a valid JSON Schema with type: "object". Supported property types: string, boolean, number, integer, array.

{
    "type": "object",
    "properties": {
        "found": {
            "type": "boolean",
            "description": "Whether the information was found"
        },
        "confidence": {
            "type": "number",
            "description": "Confidence score from 0.0 to 1.0"
        },
        "summary": {
            "type": "string",
            "description": "Summary of findings"
        },
        "sources": {
            "type": "array",
            "description": "URLs where information was found"
        }
    },
    "required": ["found", "confidence", "summary"],
    "additionalProperties": false
}

Available Tools

The agent autonomously decides which tools to use during research:

Tool	What it does	Cost per use
Google Search	Searches Google with localized results (country/language)	1 credit
Web Scraper	Fetches and reads full page content directly	1 credit
Proxy Scraper	Fetches pages through a proxy when direct scraping is blocked	2 credits

The agent typically searches first, then reads relevant pages to verify and extract detailed information. If direct scraping is blocked, it may retry with the proxy scraper at 2 credits per call.

Available Models

Model	Best for	Relative cost
`google/gemini-2.5-flash`	Fast, cheap research tasks	Lowest
`google/gemini-2.5-flash-lite`	Ultra-cheap simple lookups	Very low
`anthropic/claude-sonnet-4.6`	Complex reasoning, nuanced research	Medium
`openai/gpt-4.1-mini`	Balanced speed and quality	Low

Cheaper models work well for straightforward lookups. Use more capable models for tasks requiring nuanced judgment or multi-step reasoning.

Examples

Output Fields

The output fields match exactly what you defined in your schema.

Credit Calculation

Credits are reserved upfront based on model cost and max_steps, then adjusted down to actual usage after completion.

Component	How it's calculated
Token cost	Model's per-token price with margin, converted to credits
Tool calls	Google Search: 1 credit, Web Scraper: 1 credit, Proxy Scraper: 2 credits per call
Minimum	1 credit

Typical costs:

Simple lookup with gemini-2.5-flash (2-3 steps): 3-10 credits
Detailed research with claude-sonnet-4.6 (5 steps): 30-80 credits

Error Responses

Validation Error (422)

{
    "message": "The schema.type field must be object.",
    "errors": {
        "schema.type": ["The schema.type field must be object."]
    }
}

Common validation errors:

system_prompt and user_prompt are required
schema.type must be object with at least one property
schema.properties.*.type must be one of: string, boolean, number, integer, array
max_steps must be between 1 and 20
Unknown model (not available in our model catalog)

Failed Enrichment (422)

{
    "id": 456,
    "type": "ai_research_agent",
    "status": "failed",
    "output": null,
    "error_message": "AI agent encountered an error during research"
}

Tips

Start with fewer steps (max_steps: 3) and increase if results are incomplete
Be specific in your prompts — tell the agent exactly what to look for and where
Use gemini-2.5-flash for simple lookups — it's fast and cheap
Use claude-sonnet-4.6 when the task requires nuanced reasoning
Define clear schemas with descriptions on each property — the AI uses these to understand what you want
For bulk research, use the async API with callback_url