DatasetRow

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/riveterhq-com/json-schema/riveterhq-com-dataset-row-schema.json",
  "title": "DatasetRow",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/riveterhq-com-openapi.json#/components/schemas/DatasetRow",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "row_..."
    },
    "position": {
      "type": "integer",
      "description": "Insertion order, from 1 (the row number a user sees); stable, and the paging cursor"
    },
    "input": {
      "type": "object",
      "additionalProperties": {
        "type": [
          "string",
          "null"
        ]
      },
      "description": "Input values by column name"
    },
    "cells": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/DatasetCell"
      },
      "description": "Cells by output column name (every output column is present; in a run's `output.rows`, only the columns the fill covered)"
    },
    "credits": {
      "type": "number",
      "description": "Credits fills have charged for this row so far (each row run counted once)"
    },
    "not_found_reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "The agent's one sentence on what it could not find on this row and why, from its last successful run; null when it found every column or has not run"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "$defs": {
    "DatasetCell": {
      "type": "object",
      "properties": {
        "value": {
          "description": "The cell value (a string, or structured JSON when the column has an output_schema); null until filled or when nothing was found",
          "nullable": true
        },
        "state": {
          "type": "string",
          "enum": [
            "pending",
            "running",
            "ok",
            "not_found",
            "failed",
            "manual",
            "stale"
          ],
          "description": "pending = never filled; running = a fill is on it; ok / not_found / failed = the last fill's result\n(a failed cell never finished — the next fill re-runs it without force; a not_found cell is an answer and stays);\nmanual = set by hand (PATCH rows/{row_id}); stale = filled before the column's prompt or schema changed (the next fill re-runs it)\n"
        },
        "reason": {
          "type": "string",
          "enum": [
            "credit_limit",
            "provider",
            "internal"
          ],
          "description": "Failed cells only. credit_limit = the account's credit limit refused the row's charge; provider = the model\nprovider answered with an error or did not answer (run it again); internal = something went wrong on Riveter's\nside (run it again). A stopped run leaves no failed cells: its recorded values land as ok, the rest stay as they were.\n"
        },
        "error": {
          "type": "string",
          "description": "Failed cells only. One fixed sentence for the `reason`, fit to show a user"
        },
        "sources": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "URLs the agent cited, when present"
        }
      }
    }
  }
}