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
`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.

The agent calls its tools and returns your schema as JSON in the same request, so the model must support both together. Google models (google/..., Gemini) reject that combination and are refused with a validation error before any credits are reserved.

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	4× the model's per-token price, converted to credits and rounded up
Tool calls	Google Search: 1 credit, Web Scraper: 1 credit, Proxy Scraper: 2 credits per call
Minimum	1 credit

Typical costs:

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)
Model that cannot combine tool calls with structured JSON output (all Google/Gemini models)

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 openai/gpt-4.1-mini for simple lookups, it is the cheaper model in the table above
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