RunResult

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/agentik-cc/json-schema/agentik-cc-run-result-schema.json",
  "title": "RunResult",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/agentik-cc-openapi.yml#/components/schemas/RunResult",
  "type": "object",
  "required": [
    "run_id",
    "tool_id",
    "status",
    "price_quoted_usd",
    "price_billed_usd",
    "duration_ms",
    "balance_usd",
    "output"
  ],
  "properties": {
    "run_id": {
      "type": "string"
    },
    "tool_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "COMPLETED",
        "FAILED",
        "RUNNING"
      ]
    },
    "http_status": {
      "type": [
        "integer",
        "null"
      ]
    },
    "price_quoted_usd": {
      "type": "number"
    },
    "price_billed_usd": {
      "type": "number"
    },
    "billed_units": {
      "type": "number"
    },
    "duration_ms": {
      "type": "integer"
    },
    "balance_usd": {
      "type": "number",
      "description": "Paid USD balance; can be negative after disclosed actual-cost settlement. New calls stop while an amount is owed."
    },
    "amount_owed_usd": {
      "type": "number",
      "minimum": 0,
      "description": "Unpaid actual usage after settlement; present only for a negative paid balance. No automatic card charge."
    },
    "available_usd": {
      "type": "number",
      "description": "Spendable credit including eligible promotional credit, or zero while a paid amount is owed; actual-cost tools require paid credit."
    },
    "promo_balance": {
      "$ref": "#/$defs/PromoBalance"
    },
    "output": {
      "description": "Upstream response, shaped by the tool spec; null on failure"
    },
    "attribution": {
      "type": "string",
      "description": "Credit the data's licence asks for, on completed runs of tools that have one. Show it wherever you show this output."
    },
    "output_truncated": {
      "type": "boolean",
      "description": "True when the output exceeded the size limit and was shortened; see output_truncation"
    },
    "output_truncation": {
      "$ref": "#/$defs/OutputTruncation"
    },
    "error": {
      "type": "string"
    },
    "replayed": {
      "type": "boolean",
      "description": "True when an Idempotency-Key replayed a previous run"
    },
    "route": {
      "type": "object",
      "description": "Routed tools (agentik/...): which provider answered and every attempt, each billed as a direct call of that tool. run_id is the serving attempt; prices are the sum of all attempts. A replay confirms the run but cannot show its output again.",
      "required": [
        "served_by",
        "tried",
        "max_cost_usd"
      ],
      "properties": {
        "served_by": {
          "type": [
            "string",
            "null"
          ]
        },
        "tried": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "tool_id",
              "outcome",
              "charged_usd"
            ],
            "properties": {
              "tool_id": {
                "type": "string"
              },
              "outcome": {
                "type": "string",
                "enum": [
                  "served",
                  "empty",
                  "failed",
                  "pending",
                  "refused",
                  "rate_limited",
                  "over_budget",
                  "skipped"
                ]
              },
              "run_id": {
                "type": "string"
              },
              "charged_usd": {
                "type": "number"
              },
              "reserved_usd": {
                "type": "number",
                "description": "Still reserved while this provider's consumption is reconciled"
              },
              "code": {
                "type": "string"
              },
              "error": {
                "type": "string"
              }
            }
          }
        },
        "max_cost_usd": {
          "type": "number"
        },
        "ignored_inputs": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Inputs the serving provider cannot apply"
        }
      }
    },
    "settlement": {
      "type": "object",
      "description": "Deferred settlement: the reservation is settled when the upstream resource ends",
      "properties": {
        "pending": {
          "type": "boolean"
        },
        "upstream_id": {
          "type": "string"
        },
        "reserved_usd": {
          "type": "number"
        },
        "expires_at": {
          "type": "string"
        },
        "how": {
          "type": "string"
        }
      }
    }
  },
  "$defs": {
    "OutputTruncation": {
      "type": "object",
      "description": "Present when output_truncated. With method structural, output is valid JSON of the original shape: the listed arrays and objects keep their first elements or keys, the listed strings keep their beginning followed by a '…[truncated: N of M chars omitted]' suffix. With method raw (last resort), output is { truncated_json } holding the start of the serialized output.",
      "required": [
        "method",
        "limit_chars",
        "original_chars",
        "returned_chars",
        "omitted",
        "note"
      ],
      "properties": {
        "method": {
          "type": "string",
          "enum": [
            "structural",
            "raw"
          ]
        },
        "limit_chars": {
          "type": "integer",
          "description": "Maximum compact JSON length of output"
        },
        "original_chars": {
          "type": "integer"
        },
        "returned_chars": {
          "type": "integer"
        },
        "omitted": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "path",
              "type",
              "unit",
              "kept",
              "total"
            ],
            "properties": {
              "path": {
                "type": "string",
                "description": "JSONPath of the shortened node"
              },
              "type": {
                "type": "string",
                "enum": [
                  "array",
                  "object",
                  "string"
                ]
              },
              "unit": {
                "type": "string",
                "enum": [
                  "items",
                  "keys",
                  "chars"
                ]
              },
              "kept": {
                "type": "integer"
              },
              "total": {
                "type": "integer"
              }
            }
          }
        },
        "omitted_not_listed": {
          "type": "integer",
          "description": "Further shortened nodes not listed"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "PromoBalance": {
      "type": "object",
      "description": "Promotional credit is used first on eligible non-video calls up to max_call_usd. expires_at is the next lot expiry.",
      "properties": {
        "available_usd": {
          "type": "string"
        },
        "expires_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "max_call_usd": {
          "type": "string"
        }
      }
    }
  }
}