Exa Research Tasks

Manage asynchronous research tasks with exa-ai for complex, multi-step research workflows.

Use --help to see available commands and verify usage before running:

exa-ai <command> --help

Working with Complex Shell Commands

When using the Bash tool with complex shell syntax, follow these best practices for reliability:

• Run commands directly: Capture JSON output directly rather than nesting command substitutions

• Parse in subsequent steps: Use jq to parse output in a follow-up command if needed

• Avoid nested substitutions: Complex nested $(...) can be fragile; break into sequential steps

Example:

Less reliable: nested command substitution

results=$(exa-ai research-start --instructions "query" | jq -r '.result')

More reliable: run directly, then parse

exa-ai research-start --instructions "query"

Then in a follow-up command if needed:

exa-ai research-get research_id | jq -r '.result'

Cost Optimization

Pricing

Research is the most expensive Exa endpoint:

• Agent search: $0.005 per search operation

• Standard page read: $0.005 per page

• Pro page read: $0.010 per page (2x standard)

• Reasoning tokens: $0.000005 per token

Cost strategy:

• Avoid research unless required: Most expensive option (2-10x cost premium over other endpoints)

• Use only for autonomous, multi-step reasoning tasks that justify the cost

• For simpler queries, use search , answer , or get-contents instead

• Consider using exa-research (standard) instead of exa-research-pro unless you need the higher quality

Research Overview

Research tasks are asynchronous operations that allow you to:

• Run complex, multi-step research workflows

• Process large amounts of information over time

• Monitor progress of long-running research

• Get structured output from comprehensive research

When to Use Research vs Search

Use research-start when:

• The research requires multiple steps or complex reasoning

• You need comprehensive analysis of a topic

• The task will take significant time to complete

• You want structured, synthesized output

Use search (from exa-core) when:

• You need immediate results

• The query is straightforward

• You want quick factual information

Commands

research-start

Initiate a new research task with instructions.

exa-ai research-start --instructions "Find the top 10 Ruby performance optimization techniques"

For detailed options and examples, consult REFERENCE.md.

research-get

Check status and retrieve results of a research task.

exa-ai research-get research_abc123

For detailed options and examples, consult REFERENCE.md.

research-list

List all your research tasks with pagination.

exa-ai research-list --limit 10

For detailed options and examples, consult REFERENCE.md.

Research Models

• exa-research (default): Balanced speed and quality

• exa-research-pro: Higher quality, more comprehensive results

• exa-research-fast: Faster results, good for simpler research

Quick Examples

Simple Research

exa-ai research-start
--instructions "Find the latest breakthroughs in quantum computing"

Research with Structured Output

exa-ai research-start
--instructions "Compare TypeScript vs Flow for type checking"
--output-schema '{ "type":"object", "properties":{ "typescript":{ "type":"object", "properties":{ "pros":{"type":"array","items":{"type":"string"}}, "cons":{"type":"array","items":{"type":"string"}} } }, "flow":{ "type":"object", "properties":{ "pros":{"type":"array","items":{"type":"string"}}, "cons":{"type":"array","items":{"type":"string"}} } } } }'

Background Research Workflow

Start research

research_id=$(exa-ai research-start
--instructions "Analyze competitor landscape for project management tools" | jq -r '.research_id')

Check status later

status=$(exa-ai research-get $research_id | jq -r '.status')

Get results when complete

if [ "$status" = "completed" ]; then exa-ai research-get $research_id | jq -r '.result' fi

Use Pro Model for Comprehensive Research

exa-ai research-start
--instructions "Comprehensive analysis of microservices vs monolithic architecture with case studies"
--model exa-research-pro
--events

Shared Requirements

Schema Design

MUST: Use object wrapper for schemas

Applies to: answer, search, find-similar, get-contents

When using schema parameters (--output-schema or --summary-schema ), always wrap properties in an object:

{"type":"object","properties":{"field_name":{"type":"string"}}}

DO NOT use bare properties without the object wrapper:

{"properties":{"field_name":{"type":"string"}}} // ❌ Missing "type":"object"

Why: The Exa API requires a valid JSON Schema with an object type at the root level. Omitting this causes validation errors.

Examples:

✅ CORRECT - object wrapper included

exa-ai search "AI news"
--summary-schema '{"type":"object","properties":{"headline":{"type":"string"}}}'

❌ WRONG - missing object wrapper

exa-ai search "AI news"
--summary-schema '{"properties":{"headline":{"type":"string"}}}'

Output Format Selection

MUST NOT: Mix toon format with jq

Applies to: answer, context, search, find-similar, get-contents

toon format produces YAML-like output, not JSON. DO NOT pipe toon output to jq for parsing:

❌ WRONG - toon is not JSON

exa-ai search "query" --output-format toon | jq -r '.results'

✅ CORRECT - use JSON (default) with jq

exa-ai search "query" | jq -r '.results[].title'

✅ CORRECT - use toon for direct reading only

exa-ai search "query" --output-format toon

Why: jq expects valid JSON input. toon format is designed for human readability and produces YAML-like output that jq cannot parse.

SHOULD: Choose one output approach

Applies to: answer, context, search, find-similar, get-contents

Pick one strategy and stick with it throughout your workflow:

Approach 1: toon only - Compact YAML-like output for direct reading

• Use when: Reading output directly, no further processing needed

• Token savings: ~40% reduction vs JSON

• Example: exa-ai search "query" --output-format toon

Approach 2: JSON + jq - Extract specific fields programmatically

• Use when: Need to extract specific fields or pipe to other commands

• Token savings: ~80-90% reduction (extracts only needed fields)

• Example: exa-ai search "query" | jq -r '.results[].title'

Approach 3: Schemas + jq - Structured data extraction with validation

• Use when: Need consistent structured output across multiple queries

• Token savings: ~85% reduction + consistent schema

• Example: exa-ai search "query" --summary-schema '{...}' | jq -r '.results[].summary | fromjson'

Why: Mixing approaches increases complexity and token usage. Choosing one approach optimizes for your use case.

Shell Command Best Practices

MUST: Run commands directly, parse separately

Applies to: monitor, search (websets), research, and all skills using complex commands

When using the Bash tool with complex shell syntax, run commands directly and parse output in separate steps:

❌ WRONG - nested command substitution

webset_id=$(exa-ai webset-create --search '{"query":"..."}' | jq -r '.webset_id')

✅ CORRECT - run directly, then parse

exa-ai webset-create --search '{"query":"..."}'

Then in a follow-up command:

webset_id=$(cat output.json | jq -r '.webset_id')

Why: Complex nested $(...) command substitutions can fail unpredictably in shell environments. Running commands directly and parsing separately improves reliability and makes debugging easier.

MUST NOT: Use nested command substitutions

Applies to: All skills when using complex multi-step operations

Avoid nesting multiple levels of command substitution:

❌ WRONG - deeply nested

result=$(exa-ai search "$(cat query.txt | tr '\n' ' ')" --num-results $(cat config.json | jq -r '.count'))

✅ CORRECT - sequential steps

query=$(cat query.txt | tr '\n' ' ') count=$(cat config.json | jq -r '.count') exa-ai search "$query" --num-results $count

Why: Nested command substitutions are fragile and hard to debug when they fail. Sequential steps make each operation explicit and easier to troubleshoot.

SHOULD: Break complex commands into sequential steps

Applies to: All skills when working with multi-step workflows

For readability and reliability, break complex operations into clear sequential steps:

❌ Less maintainable - everything in one line

exa-ai webset-create --search '{"query":"startups","count":1}' | jq -r '.webset_id' | xargs -I {} exa-ai webset-search-create {} --query "AI" --behavior override

✅ More maintainable - clear steps

exa-ai webset-create --search '{"query":"startups","count":1}' webset_id=$(jq -r '.webset_id' < output.json) exa-ai webset-search-create $webset_id --query "AI" --behavior override

Why: Sequential steps are easier to understand, debug, and modify. Each step can be verified independently.