RIriveterhq
Tools

search agent

Changed on

Ask a question and get an answer. This is meant for quick, relatively scoped one-off questions, like "What is the NAICS code for this company...". For more complex questions, use the enrich/ endpoint.

This uses the same AI + web-tool loop that fills a single agent-mode cell in an enrichment (web search, web scraping, PDF reading, HTTP requests), with no enrichment setup.

The run is processed in the background while this request long-polls up to wait seconds (default 50) — most runs finish in time and return the answer inline in output.result. If the agent is still working when the budget elapses, the response comes back with status: processing and output: null; poll GET /runs/{id}/result (it long-polls too) until the run is terminal.

Pass output_schema (a JSON Schema object) to get output.result back as a structured object matching your schema instead of free text. Unanswerable questions return the string "not found".

Quick example

curl -X POST https://api.riveterhq.com/v1/search_agent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Who is the current CEO of Anthropic, and when did they take the role?"}'

Credit costs

  • 1 credit per call (same as one agent-mode enrichment cell), charged when the agent completes. Failed runs are not charged.
post/search_agent

Request

Request body

promptstring required

The question or task for the agent

output_schemaobject

Optional JSON Schema object for the answer, e.g. {"type": "object", "properties": {"ceo_name": {"type": "string"}}}. When set, output.result is an object matching this schema.

waitinteger

Seconds to hold this request waiting for the answer (default and max 50). Pass 0 to return immediately and poll GET /runs/{id}/result instead.

run_keystring

Optional idempotency key (becomes the run id "run_<run_key>")

estimate_costboolean

Validate and price the request without running or charging anything; the 200 response is the credit estimate (EstimateCostResult).

max_creditsnumber

Credit ceiling. Refused with 422 credit_cap_exceeded (nothing charged) when the estimate's maximum exceeds it.

Response

estimate_cost only — the flat per-call price; nothing was started

estimate_costtrue required
type'enrichment' | 'dataset_build' | 'extraction_discovery' | 'extraction' | 'monitor' | 'scrape' | 'quick_search' | 'search_agent' required

What would have been charged for (monitor = one scheduled run of the monitor)

Example response

{
  "estimate_cost": true,
  "type": "enrichment",
  "credit_detail": {
    "estimate": {
      "minimum": 0,
      "maximum": 1920,
      "charged_upfront": false
    },
    "credits_used": 0,
    "credits_remaining": 5000,
    "sufficient_credits": true
  }
}

Changes

  • fac56b649559Revision changes
    • warning

      removed the optional property //// from the response with the status

  • dcb4d45ade1aRevision changes
    • info

      added the optional property ////////// to the response with the status

    • info

      added the optional property ////////// to the response with the status

    • info

      added the optional property ////// to the response with the status

    • info

      added the optional property ////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status