Run

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/lexifina/json-schema/lexifina-run-schema.json",
  "title": "Run",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/lexifina-openapi.json#/components/schemas/Run",
  "properties": {
    "run_id": {
      "title": "Run Id",
      "type": "string"
    },
    "session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Session Id"
    },
    "document_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Document Id"
    },
    "status": {
      "description": "queued, running, cancel_requested (a stop was requested; the run is stopping), completed, failed, cancelled or interrupted.",
      "title": "Status",
      "type": "string"
    },
    "is_terminal": {
      "description": "True once status is completed, failed, cancelled or interrupted.",
      "title": "Is Terminal",
      "type": "boolean"
    },
    "source": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Where the run was started: api, web or word-addin; null for work the agent started itself, such as a goal's next step.",
      "title": "Source"
    },
    "prompt_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Prompt Text"
    },
    "answer_text": {
      "description": "Everything the agent wrote in the run, including its progress commentary along the way. Citations appear as [label] and are listed in references.",
      "title": "Answer Text",
      "type": "string"
    },
    "final_answer_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The agent's closing message only, without the progress commentary in answer_text. Null until the agent has written one.",
      "title": "Final Answer Text"
    },
    "references": {
      "items": {
        "$ref": "#/$defs/Reference"
      },
      "title": "References",
      "type": "array"
    },
    "proposed_changes": {
      "description": "Changes staged for review; decide them with the review operations.",
      "items": {
        "$ref": "#/$defs/ProposedChange"
      },
      "title": "Proposed Changes",
      "type": "array"
    },
    "pending_user_input": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "A question the run, or one of its subagent runs, is waiting on: request_id, questions (each with id, header, question and options), run_id (the run that asked) and, for a subagent's question, subagent (run_id, session_id, parent_run_id, profile, title, status). Answer it with the user-input operation on this run. An approval's question has id hook_approval and takes one of its option labels. delivery async marks an optional question that does not pause the run. On a finished run, status deferred marks an optional question it left open: answering it starts the session's next run.",
      "title": "Pending User Input"
    },
    "plan": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "In plan mode: the plan the agent proposes. Nothing is changed until you run it.",
      "title": "Plan"
    },
    "created_documents": {
      "items": {},
      "title": "Created Documents",
      "type": "array"
    },
    "error": {
      "anyOf": [
        {
          "$ref": "#/$defs/RunError"
        },
        {
          "type": "null"
        }
      ]
    },
    "usage": {
      "$ref": "#/$defs/RunUsage"
    },
    "output_status": {
      "description": "Structured output, when the run was started with an output_schema.",
      "enum": [
        "not_requested",
        "pending",
        "completed",
        "failed"
      ],
      "title": "Output Status",
      "type": "string"
    },
    "output": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "JSON matching the run's output_schema, once output_status is completed.",
      "title": "Output"
    },
    "output_error": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "Why extraction failed: code and message.",
      "title": "Output Error"
    },
    "items": {
      "anyOf": [
        {
          "items": {
            "oneOf": [
              {
                "$ref": "#/$defs/RunMessageItem"
              },
              {
                "$ref": "#/$defs/RunToolItem"
              },
              {
                "$ref": "#/$defs/RunStageItem"
              },
              {
                "$ref": "#/$defs/RunSubagentItem"
              }
            ]
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Present when requested with include=items.",
      "title": "Items"
    },
    "external_reference": {
      "anyOf": [
        {
          "$ref": "#/$defs/ExternalReferenceValue"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "created_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Created At"
    },
    "started_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Started At"
    },
    "completed_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Completed At"
    },
    "duration_ms": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Duration Ms"
    },
    "id": {
      "description": "The run id (run_id).",
      "title": "Id",
      "type": "string"
    },
    "object": {
      "const": "run",
      "default": "run",
      "title": "Object",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "session_id",
    "document_id",
    "status",
    "is_terminal",
    "source",
    "prompt_text",
    "answer_text",
    "final_answer_text",
    "references",
    "proposed_changes",
    "pending_user_input",
    "plan",
    "created_documents",
    "error",
    "usage",
    "output_status",
    "output",
    "output_error",
    "items",
    "external_reference",
    "created_at",
    "started_at",
    "completed_at",
    "duration_ms",
    "id",
    "object"
  ],
  "type": "object",
  "$defs": {
    "ExternalReferenceValue": {
      "properties": {
        "external_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "External Id"
        },
        "metadata": {
          "additionalProperties": {
            "type": "string"
          },
          "default": {},
          "title": "Metadata",
          "type": "object"
        }
      },
      "title": "ExternalReferenceValue",
      "type": "object",
      "required": [
        "external_id",
        "metadata"
      ]
    },
    "ProposedChange": {
      "properties": {
        "proposal_id": {
          "title": "Proposal Id",
          "type": "string"
        },
        "proposal_revision": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Proposal Revision"
        },
        "state": {
          "description": "proposed, applied, modified, rejected or invalidated.",
          "title": "State",
          "type": "string"
        },
        "section_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Section Id"
        },
        "section_uuid": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Section Uuid"
        },
        "change_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Change Type"
        },
        "original_text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Original Text"
        },
        "suggested_text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Suggested Text"
        },
        "edit_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "How many passages the change edits. Accepting it applies every one; original_text and suggested_text show them all, one paragraph per passage.",
          "title": "Edit Count"
        },
        "explanation": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Explanation"
        },
        "warnings": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Problems found when the change was staged, such as wording the agent meant to keep but did not. Show them to the user with the change.",
          "title": "Warnings"
        },
        "apply_allowed": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Apply Allowed"
        },
        "apply_block_reason": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Apply Block Reason"
        },
        "review_group_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Review Group Id"
        },
        "review_group_atomic": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Review Group Atomic"
        }
      },
      "required": [
        "proposal_id",
        "proposal_revision",
        "state",
        "section_id",
        "section_uuid",
        "change_type",
        "original_text",
        "suggested_text",
        "edit_count",
        "explanation",
        "warnings",
        "apply_allowed",
        "apply_block_reason",
        "review_group_id",
        "review_group_atomic"
      ],
      "title": "ProposedChange",
      "type": "object"
    },
    "Reference": {
      "properties": {
        "reference_id": {
          "title": "Reference Id",
          "type": "string"
        },
        "label": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Label"
        },
        "document_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Document Id"
        },
        "version": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Version"
        },
        "section_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Section Id"
        },
        "section_uuid": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Section Uuid"
        },
        "text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Text"
        }
      },
      "required": [
        "reference_id",
        "label",
        "document_id",
        "version",
        "section_id",
        "section_uuid",
        "text"
      ],
      "title": "Reference",
      "type": "object"
    },
    "RunError": {
      "properties": {
        "code": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "run_spend_limit_reached when the key's per-run spending limit stopped the run.",
          "title": "Code"
        },
        "message": {
          "description": "Why the run did not complete, such as \"Cancelled by user\".",
          "title": "Message",
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "title": "RunError",
      "type": "object"
    },
    "RunMessageItem": {
      "description": "The request (user_message), the agent's answer (agent_message) or, with include=thinking, its reasoning.",
      "properties": {
        "item_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Item Id"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "in_progress, completed, failed or cancelled.",
          "title": "Status"
        },
        "created_at": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Created At"
        },
        "item_type": {
          "enum": [
            "user_message",
            "agent_message",
            "thinking"
          ],
          "title": "Item Type",
          "type": "string"
        },
        "text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Text"
        }
      },
      "required": [
        "item_id",
        "status",
        "created_at",
        "item_type",
        "text"
      ],
      "title": "RunMessageItem",
      "type": "object"
    },
    "RunStageItem": {
      "description": "A stage of the run, such as planning or drafting.",
      "properties": {
        "item_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Item Id"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "in_progress, completed, failed or cancelled.",
          "title": "Status"
        },
        "created_at": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Created At"
        },
        "item_type": {
          "const": "stage",
          "title": "Item Type",
          "type": "string"
        },
        "label": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Label"
        }
      },
      "required": [
        "item_id",
        "status",
        "created_at",
        "item_type",
        "label"
      ],
      "title": "RunStageItem",
      "type": "object"
    },
    "RunSubagent": {
      "description": "A subagent run a step started. Retrieve it by run_id for its own answer and activity.",
      "properties": {
        "run_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Run Id"
        },
        "session_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Session Id"
        },
        "profile": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The subagent's role, such as researcher or verifier.",
          "title": "Profile"
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The task it was given, in a few words.",
          "title": "Title"
        },
        "prompt_preview": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The start of its instructions.",
          "title": "Prompt Preview"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "queued, running, cancel_requested, completed, failed, cancelled or interrupted.",
          "title": "Status"
        },
        "awaiting_input": {
          "default": false,
          "description": "It is waiting on a question; the run's pending_user_input shows it.",
          "title": "Awaiting Input",
          "type": "boolean"
        },
        "summary": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "What it reported, once finished.",
          "title": "Summary"
        },
        "edits_proposed": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Edits Proposed"
        }
      },
      "required": [
        "run_id",
        "session_id",
        "profile",
        "title",
        "prompt_preview",
        "status",
        "awaiting_input",
        "summary",
        "edits_proposed"
      ],
      "title": "RunSubagent",
      "type": "object"
    },
    "RunSubagentItem": {
      "description": "A subagent the agent started. Retrieve subagent.run_id for its own answer and activity.",
      "properties": {
        "item_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Item Id"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "in_progress, completed, failed or cancelled.",
          "title": "Status"
        },
        "created_at": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Created At"
        },
        "item_type": {
          "const": "subagent",
          "title": "Item Type",
          "type": "string"
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Title"
        },
        "summary": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Summary"
        },
        "activity": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "\"Waiting for an answer\" while its question is open.",
          "title": "Activity"
        },
        "subagent": {
          "anyOf": [
            {
              "$ref": "#/$defs/RunSubagent"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "item_id",
        "status",
        "created_at",
        "item_type",
        "title",
        "summary",
        "activity",
        "subagent"
      ],
      "title": "RunSubagentItem",
      "type": "object"
    },
    "RunToolItem": {
      "description": "A tool the agent used.",
      "properties": {
        "item_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Item Id"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "in_progress, completed, failed or cancelled.",
          "title": "Status"
        },
        "created_at": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Created At"
        },
        "item_type": {
          "const": "tool",
          "title": "Item Type",
          "type": "string"
        },
        "tool_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Tool Name"
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Title"
        },
        "summary": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Summary"
        },
        "activity": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "What it is doing, as the app says it, such as \"Searching the web\" while it runs and \"Web search complete\" once done.",
          "title": "Activity"
        }
      },
      "required": [
        "item_id",
        "status",
        "created_at",
        "item_type",
        "tool_name",
        "title",
        "summary",
        "activity"
      ],
      "title": "RunToolItem",
      "type": "object"
    },
    "RunUsage": {
      "description": "What the run has used. While it runs these are the totals so far; once it is final, its totals.\nThe token counts and cost cover the run and the subagent runs it started.",
      "properties": {
        "model_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The model the run works with.",
          "title": "Model Id"
        },
        "model_invocation_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Model Invocation Count"
        },
        "input_tokens": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Input tokens so far, including subagent runs.",
          "title": "Input Tokens"
        },
        "output_tokens": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Output tokens so far, including subagent runs.",
          "title": "Output Tokens"
        },
        "total_tokens": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Total Tokens"
        },
        "estimated_cost_usd": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "What the model calls have cost so far (final once is_terminal is true), including subagent runs, priced as the matter ledger prices AI usage.",
          "title": "Estimated Cost Usd"
        },
        "subagent_run_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Subagent runs the run has started.",
          "title": "Subagent Run Count"
        },
        "subagent_estimated_cost_usd": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The part of estimated_cost_usd spent by subagent runs.",
          "title": "Subagent Estimated Cost Usd"
        }
      },
      "required": [
        "model_id",
        "model_invocation_count",
        "input_tokens",
        "output_tokens",
        "total_tokens",
        "estimated_cost_usd",
        "subagent_run_count",
        "subagent_estimated_cost_usd"
      ],
      "title": "RunUsage",
      "type": "object"
    }
  }
}