Runs

The run plus output, null until the run finishes.

Pass ?wait=N (max 50) to long-poll: the request holds until the run finishes or the budget elapses, whichever comes first.

Output shape by run type

  • enrichment — an object mapping column headers to arrays of cell objects: { "Company": [{"value": "Apple"}], "CEO": [{"value": "Tim Cook"}] }
  • dataset_build — the same columnar shape as enrichment
  • extraction — the extracted records as an array of JSON objects (matching your output_record_json_schema)
  • quick_search — the search result object { "results": [{ "title", "link", "snippet" }, ...], "knowledge_graph"? }, the same data the synchronous POST /quick_search response already carried.
  • search_agent — the answer object { "result": <string or object> }; result matches the request's output_schema when one was given, otherwise it's free text.
  • enrichment on a dataset (POST /enrich with dataset_id) — { "rows": [...] }: only the rows the fill ran, in position order, each in the /datasets/{id}/rows shape (id, position, input, cells limited to the columns the fill covered, credits). GET /datasets/{id}/rows is the live view. Above 5,000 rows, or after the rows expire (30 days), output is null and output_files (signed CSV and JSONL links to the whole grid; pending until the export lands, valid one hour, see expires_at) are the output.
  • enrichment started on POST /enrich_rows, or on POST /enrich with input — the columnar shape while rows are ≤ 5,000, plus the same output_files. Above 5,000 rows, or after the rows expire (30 days), output is null and the files are the output.
get/runs/{id}/result

Request

Path parameters

idstring required

The run id (run_...)

Query parameters

waitinteger

Long-poll budget in seconds (0–50, default 0)

Response

The run with output (null while still running)

idstring required

The run id (run_...)

type'enrichment' | 'dataset_build' | 'extraction' | 'scrape' | 'quick_search' | 'search_agent' required

What kind of run this is

status'pending' | 'enqueued' | 'processing' | 'success' | 'stopped' required
credits_usednumber

Credits consumed so far

app_urlstring uri

Link to view this run in the Riveter app

result_urlstring uri required

Where to fetch the run's output

started_atstring date-time nullable
finished_atstring date-time nullable
stopped_reason'user_request' | 'credit_limit' | 'error'

Why the run has status stopped. Only present on stopped runs. user_request: stopped through the API or the app. credit_limit: the account ran out of credits. error: the run failed (internal error, or every enrichment cell failed); error.message has the detail.

enrichment_idstring

Present when the run belongs to an enrichment

enrichment_namestring
dataset_idstring

Present on dataset-build runs

extraction_idstring

Present on extraction runs

monitor_idstring

Present on monitor-scheduled runs

webhook_urlstring uri

Present when the run has a webhook configured

Example response

{
  "id": "run_018f6a70-1234-7abc-89ab-0123456789ab",
  "type": "enrichment",
  "status": "processing",
  "progress": {
    "percent_complete": 40,
    "estimated_seconds_remaining": 90,
    "elapsed_seconds": 60,
    "completed_cells": 4,
    "total_cells_expected": 10,
    "not_found_cells": 0
  },
  "credits_used": 2.5,
  "credit_detail": {
    "estimate": {
      "minimum": 0,
      "maximum": 10,
      "charged_upfront": false
    },
    "credits_used": 2.5
  },
  "app_url": "https://app.riveterhq.com/runs/run_018f6a70-1234-7abc-89ab-0123456789ab",
  "result_url": "https://api.riveterhq.com/v1/runs/run_018f6a70-1234-7abc-89ab-0123456789ab/result",
  "started_at": "2026-01-15T12:00:00Z",
  "finished_at": null,
  "error": null,
  "enrichment_id": "enr_018f5b60-1234-7abc-89ab-0123456789ab",
  "enrichment_name": "My Enrichment"
}

Changes

    • warning

      removed the optional property //// from 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