v0.1.0-beta

OpenAPI 3.1.0

Submit an asynchronous research Agent run.

Felo API Support

MIT

Server

https://openapi.felo.ai

Client Libraries

Shell Curl

Exa

Semantic search, page content, cited answers and asynchronous research.

Exa Operations

post/v1/beta/exa/agent/runs

Submit an asynchronous research Agent run.

Submit an asynchronous research task. query and Idempotency-Key are required. Configure effort, outputSchema, dataSources and previousRunId as needed. HTTP 202 returns a job; poll get_exa_agent_run until completed, failed or cancelled. Completed output contains text, structured data and grounding. Reusing an Idempotency-Key returns the existing job. Job pricing fields are provider metadata, not Felo billing records.

Headers

Idempotency-Key
Type: string
max length:
191
required

Unique key (1 to 191 characters) that makes the submit idempotent. Re-submitting with the same key and request fingerprint returns the original run.

Body

required

application/json

query
Type: string
required

The natural-language research query.
dataSources
Type: array

Third-party data sources (Exa Connect) the Agent is granted access to.
effort
Type: string

Compute/depth tier for the run.
input
Type: object

Row-processing input: rows to process and exclusions.
- data
  Type: array
  
  Input rows for the run.
- exclusion
  
  Items to exclude from processing.
outputSchema
Type: object

JSON Schema used to validate the structured output.
previousRunId
Type: string

Continue from a previously completed run.

Responses

202
Type: object · AsyncJob

Research run accepted. The Location header points at the job resource; poll it until terminal.

An asynchronous integration job. Returned by the submit call (HTTP 202) and by the poll/detail call. Poll the job by its id until status is a terminal value (completed, failed, or cancelled).
completedAt
Type: string Format: date-timenullable

When the job reached a terminal status. Null while the job is still queued or running.

createdAt
Type: string Format: date-time

When the job was accepted.

endpoint
Type: string

Provider operation identifier stored with the job. This metadata is not a Felo polling URL; use the documented Felo job path or Location header.

error
Type: object nullable

Present when status is failed. Null otherwise.

code
Type: string

Machine-readable error code.

message
Type: string

Human-readable error message.

id
Type: string

Job identifier. Use it with the corresponding Felo polling endpoint.

object
Type: string

Always "integration_async_job".

output
nullable

Job result payload. Present only once status is completed. For Agent Runs this is the structured research result.

outputExpired
Type: boolean

True when the result has been retained past its retention window and is no longer retrievable.

pricing
Type: object
authorizedMicrosUSD
Type: integer

Provider authorization metadata in micro-USD. This is not a Felo credit hold or billing record.

billingMode
Type: string

Provider job billing mode. Felo charges follow Felo billing records.

currency
Type: string
finalMicrosUSD
Type: integer nullable

Provider settlement metadata in micro-USD, nullable before settlement. This is not the Felo charge.

status
Type: string enum

Customer-facing lifecycle status. queued and running are non-terminal; completed, failed, and cancelled are terminal.

values
queued
running
completed
failed
cancelled
application/json
400

The request could not be processed. Check the request parameters.
401

A valid Felo API key is required.
402

The request cannot proceed because a billing requirement is not met.
403

The account is not permitted to perform this operation.
409

idempotency_conflict — the same Idempotency-Key was reused with a different request body.
429

A request or spending limit has been reached.
502

The service could not complete the request.
503

The API or billing service is temporarily unavailable.
504

The service timed out while processing the request.
default

The operation failed. Keep the response request ID when contacting Felo support.

post/v1/beta/exa/agent/runs

curl https://openapi.felo.ai/v1/beta/exa/agent/runs \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "query": "Summarize the main changes in RAG evaluation methods over the past year as a bullet list.",
  "outputSchema": {},
  "input": {
    "data": [],
    "exclusion": null
  },
  "effort": "",
  "previousRunId": "",
  "dataSources": []
}'

Show Schema

{
  "id": "iaj_01HZY8Q2M4K7N9V3T6W1X0B2C3",
  "object": "integration_async_job",
  "endpoint": "/apis/v1/exa/agent/runs",
  "status": "queued",
  "createdAt": "2026-09-30T03:09:45.799Z",
  "completedAt": "2026-09-30T03:09:45.799Z",
  "pricing": {
    "currency": "USD",
    "authorizedMicrosUSD": 1,
    "finalMicrosUSD": 1,
    "billingMode": "flat_per_call"
  },
  "output": null,
  "outputExpired": true,
  "error": {
    "code": "string",
    "message": "string"
  }
}

Research run accepted. The Location header points at the job resource; poll it until terminal.

Submit an asynchronous research Agent run.

AuthenticationRequired

Exa

Submit an asynchronous research Agent run.