> ## Documentation Index > Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get account run analytics > Read run activity for the selected account, optionally narrowed to one project or label, using shared reporting controls and a human user session. Requires account.billing.read. ## OpenAPI ````yaml /cloud/rest/openapi.json get /accounts/{account_id}/analytics/runs openapi: 3.1.0 info: title: Veryfront REST API reference version: 1.0.0 description: >- ## Explore the API | Domain | Use it to | | --- | --- | | [Projects](#tag/projects) | Manage projects and files. | | [Agents](#tag/agents) | Manage agent primitives. | | [Orchestration](#tag/execution) | Manage conversations and runs. | | [Evaluations](#tag/evaluations) | Manage evaluations and results. | | [AI Gateway](#tag/ai-gateway) | Discover models, control access, run inference and measure model usage. | | [MCP](#tag/mcp) | Discover tools and authorization. | | [Integrations](#tag/integrations) | Manage connections and integrations. | | [Knowledge](#tag/knowledge) | Manage documents and search. | | [Deployments](#tag/deployments) | Manage releases and deployments. | | [Runtime](#tag/runtime) | Manage environments and infrastructure. | | [Observability](#tag/observability) | Monitor activity and performance. | | [Identity & Access](#tag/identity-access) | Manage identity and access. | | [Billing & Usage](#tag/billing-usage) | Manage billing and usage. | | [Other](#tag/platform) | Inspect health and API metadata. | [OpenAPI specification (JSON)](/openapi.json) contact: name: Veryfront API Support url: https://veryfront.com/docs email: support@veryfront.com x-api-id: 5f1f0b8a-6b0e-4c1a-9b35-0f3a1e6d84c7 x-audience: external-public servers: - url: https://api.veryfront.com security: - bearerAuth: [] - apiKeyAuth: [] tags: - name: projects description: Manage projects and files. - name: agents description: Manage agent primitives. - name: execution description: Manage conversations and runs. - name: evaluations description: Manage evaluations and results. - name: ai-gateway description: Discover models, control access, run inference and measure model usage. - name: mcp description: Discover tools and authorization. - name: integrations description: Manage connections and integrations. - name: knowledge description: Manage documents and search. - name: deployments description: Manage releases and deployments. - name: runtime description: Manage environments and infrastructure. - name: observability description: Monitor activity and performance. - name: identity-access description: Manage identity and access. - name: billing-usage description: Manage billing and usage. - name: platform description: Inspect health and API metadata. - name: projects/Projects - name: projects/Projects/Favorites - name: projects/Projects/Account Projects - name: projects/Projects/Projects - name: projects/Projects/Project Labels - name: projects/Projects/Project templates - name: projects/Files - name: projects/Files/Files - name: projects/Files/File Chunks - name: projects/Files/Branch File Versions - name: projects/Files/Branch Files - name: projects/Files/Environment Files - name: projects/Files/File Versions - name: projects/Files/Branch File Drafts - name: projects/Files/Release Files - name: projects/Files/Sandbox Files - name: projects/Files/File Search - name: projects/Branches - name: projects/Branches/Branches - name: projects/Branches/Branch Policies - name: projects/Branches/Branch Approvals - name: projects/Branches/Branch Status Checks - name: projects/Branches/Project Commits - name: projects/Branches/Branch Merges - name: projects/Uploads - name: projects/Uploads/Upload Folders - name: projects/Uploads/Upload Grants - name: projects/Uploads/Project Uploads - name: projects/Uploads/Upload Visibility - name: agents/Agents - name: agents/Agents/Agents - name: agents/Agents/Agent Labels - name: agents/Agents/Agent templates - name: agents/Agents/Agent Tool References - name: agents/Agents/Agent Avatars - name: agents/Agents/Agent Capabilities - name: agents/Agents/Agent Installation - name: agents/Prompts - name: agents/Prompts/Project prompts - name: agents/Tools - name: agents/Tools/Project tools - name: agents/Skills - name: agents/Skills/Project skills - name: agents/Resources - name: agents/Resources/Project resources - name: agents/Tasks - name: agents/Tasks/Tasks - name: agents/Workflows - name: agents/Workflows/Workflows - name: execution/Conversations - name: execution/Conversations/Conversations - name: execution/Conversations/Conversation messages - name: execution/Conversations/Conversation participants - name: execution/Conversations/Conversation read state - name: execution/Triggers - name: execution/Triggers/Project schedules - name: execution/Triggers/Webhooks - name: execution/Triggers/Webhook events - name: execution/Runs - name: execution/Runs/Run Input Requests - name: execution/Runs/Runs - name: execution/Runs/Runtime - name: execution/Runs/Child Runs - name: execution/Runs/Conversation Runs - name: execution/Runs/Project Runs - name: execution/Runs/Webhook Runs - name: execution/Runs/Run Events - name: execution/Runs/Run Actions - name: execution/Runs/Run Artifacts - name: execution/Executors - name: execution/Executors/Connected agents - name: execution/Executors/Agent workers - name: evaluations/Evaluations - name: evaluations/Evaluations/Evaluations - name: evaluations/Evaluations/Evaluation Runs - name: ai-gateway/Models - name: ai-gateway/Models/Model discovery - name: ai-gateway/Models/Inference Models - name: ai-gateway/Models/Project inference policy - name: ai-gateway/Models/Account inference policy - name: ai-gateway/Provider credentials - name: ai-gateway/Provider credentials/Account provider credentials - name: ai-gateway/Inference - name: ai-gateway/Inference/OpenAI Chat Completions - name: ai-gateway/Inference/Embeddings - name: ai-gateway/Inference/OpenAI Responses - name: ai-gateway/Inference/Proxy metadata - name: ai-gateway/Inference/Anthropic Messages - name: ai-gateway/Inference/Provider gateway - name: ai-gateway/Inference/Gemini inference - name: ai-gateway/Inference/Image generation - name: ai-gateway/Model usage - name: ai-gateway/Model usage/Model usage - name: mcp/Tools - name: mcp/Tools/MCP discovery - name: mcp/Authorization - name: mcp/Authorization/Protected resource discovery - name: integrations/Integrations - name: integrations/Integrations/Integration tools - name: integrations/Integrations/Integration catalog - name: integrations/Integrations/Project integrations - name: integrations/Connections - name: integrations/Connections/Connections - name: integrations/Channels - name: integrations/Channels/Channels - name: integrations/Channels/Setup lookups - name: integrations/External storage - name: integrations/External storage/External Files - name: knowledge/Documents - name: knowledge/Documents/Project knowledge - name: knowledge/Documents/Retrieval documents - name: knowledge/Documents/Knowledge assets - name: knowledge/Search - name: knowledge/Search/Search - name: knowledge/Embeddings - name: knowledge/Embeddings/Project embeddings - name: deployments/Releases - name: deployments/Releases/Releases - name: deployments/Releases/Release Source Manifests - name: deployments/Deployments - name: deployments/Deployments/Project deployments - name: deployments/Artifacts - name: deployments/Artifacts/Dependencies - name: deployments/Artifacts/Release Asset Manifests - name: deployments/Artifacts/Style artifacts - name: runtime/Environments - name: runtime/Environments/Environments - name: runtime/Environments/Environment Domains - name: runtime/Environments/Environment variables - name: runtime/Servers - name: runtime/Servers/Servers - name: runtime/Servers/Server Environments - name: runtime/Sandboxes - name: runtime/Sandboxes/Sandbox Lifecycle - name: runtime/Sandboxes/Sandbox Commands - name: runtime/Sandboxes/Sandbox Environment - name: runtime/Sandboxes/Sandbox Health - name: runtime/Sandboxes/Sandbox Terminal - name: runtime/Cache - name: runtime/Cache/Project Cache - name: observability/Logs - name: observability/Logs/Log entries - name: observability/Traces - name: observability/Traces/Trace spans - name: observability/Traces/Project traces - name: observability/Traces/Trace Search - name: observability/Metrics - name: observability/Metrics/Metric series - name: observability/Alerts - name: observability/Alerts/Project alerts - name: observability/Error types - name: observability/Error types/Error types - name: identity-access/Users - name: identity-access/Users/Account users - name: identity-access/Users/Project members - name: identity-access/Users/Current user - name: identity-access/Accounts - name: identity-access/Accounts/Accounts - name: identity-access/Invitations - name: identity-access/Invitations/Invitations - name: identity-access/API keys - name: identity-access/API keys/API keys - name: identity-access/Authentication - name: identity-access/Authentication/Sign-in - name: identity-access/Authentication/Tokens - name: identity-access/Authorization - name: identity-access/Authorization/Authorized apps - name: identity-access/Authorization/General OAuth - name: identity-access/Authorization/Consent - name: billing-usage/Subscriptions - name: billing-usage/Subscriptions/Subscription - name: billing-usage/Subscriptions/Seats - name: billing-usage/Billing - name: billing-usage/Billing/Billing details - name: billing-usage/Billing/Invoices and payments - name: billing-usage/Credits - name: billing-usage/Credits/Credits - name: billing-usage/Feature gates - name: billing-usage/Feature gates/Feature gates - name: billing-usage/Budgets - name: billing-usage/Budgets/Budgets - name: billing-usage/Usage - name: billing-usage/Usage/API key usage - name: billing-usage/Usage/Usage - name: billing-usage/Usage/Project usage - name: billing-usage/Analytics - name: billing-usage/Analytics/Conversation Analytics - name: billing-usage/Analytics/Run Analytics - name: platform/Other - name: platform/Other/API metadata paths: /accounts/{account_id}/analytics/runs: get: tags: - billing-usage/Analytics/Run Analytics summary: Get account run analytics description: >- Read run activity for the selected account, optionally narrowed to one project or label, using shared reporting controls and a human user session. Requires account.billing.read. operationId: getRunAnalytics parameters: - schema: type: string format: uuid required: true name: account_id in: path - $ref: '#/components/parameters/UsageQueryPreset' - $ref: '#/components/parameters/UsageQueryFrom' - $ref: '#/components/parameters/UsageQueryTo' - $ref: '#/components/parameters/UsageQueryTimezone' - $ref: '#/components/parameters/UsageQueryGranularity' - $ref: '#/components/parameters/UsageQueryGroupBy' - $ref: '#/components/parameters/UsageQueryCompare' - schema: type: - array - 'null' items: type: string required: false name: label in: query - schema: type: string description: >- Optional project UUID or slug to scope analytics to a single project. required: false description: >- Optional project UUID or slug to scope analytics to a single project. name: project_reference in: query responses: '200': description: Run activity for the selected account. content: application/json: schema: $ref: '#/components/schemas/RunAnalytics' '400': description: Bad request content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': description: Forbidden content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '404': description: Not found content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': description: Rate limit exceeded content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': description: Server error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' components: parameters: UsageQueryPreset: schema: $ref: '#/components/schemas/UsageQueryPreset' required: false description: >- Whole local days, defaulting to 30d. Explicit from/to bounds take precedence over preset, including SDK-supplied defaults. name: preset in: query UsageQueryFrom: schema: $ref: '#/components/schemas/UsageQueryFrom' required: false description: >- Inclusive start. Supply both from and to; these bounds take precedence over preset. name: from in: query UsageQueryTo: schema: $ref: '#/components/schemas/UsageQueryTo' required: false description: Exclusive end, no later than the end of today in timezone. name: to in: query UsageQueryTimezone: schema: $ref: '#/components/schemas/UsageQueryTimezone' required: false name: timezone in: query UsageQueryGranularity: schema: $ref: '#/components/schemas/UsageQueryGranularity' required: false description: UTC hours, or local calendar days, Monday-based weeks and months. name: granularity in: query UsageQueryGroupBy: schema: $ref: '#/components/schemas/UsageQueryGroupBy' required: false description: >- Grouping dimensions supported by this operation. Repeat the parameter or use a comma-separated list. name: group_by in: query style: form explode: true UsageQueryCompare: schema: $ref: '#/components/schemas/UsageQueryCompare' required: false description: >- Compare preceding calendar months for whole-month custom ranges, local days for whole-day ranges and presets, or equal elapsed duration otherwise. name: compare in: query schemas: RunAnalytics: type: object properties: scope: oneOf: - type: object properties: kind: type: string enum: - account account_id: type: string format: uuid project_id: type: - string - 'null' format: uuid required: - kind - account_id - project_id - type: object properties: kind: type: string enum: - user user_id: type: string format: uuid project_id: type: - string - 'null' format: uuid required: - kind - user_id - project_id group_by: type: array items: type: string enum: - project summary: type: object properties: total_runs: type: number description: Agent runs created in the selected interval. completed_runs: type: number description: Matching runs currently completed. failed_runs: type: number description: Matching runs currently failed. average_duration_ms: type: - number - 'null' description: Mean finished-run duration in milliseconds. p95_duration_ms: type: - number - 'null' description: 95th percentile finished-run duration in milliseconds. last_run_at: type: - string - 'null' description: Latest matching run creation timestamp. previous: type: object properties: total_runs: type: number description: Agent runs created in the selected interval. completed_runs: type: number description: Matching runs currently completed. failed_runs: type: number description: Matching runs currently failed. average_duration_ms: type: - number - 'null' description: Mean finished-run duration in milliseconds. p95_duration_ms: type: - number - 'null' description: 95th percentile finished-run duration in milliseconds. last_run_at: type: - string - 'null' description: Latest matching run creation timestamp. required: - total_runs - completed_runs - failed_runs - average_duration_ms - p95_duration_ms - last_run_at required: - total_runs - completed_runs - failed_runs - average_duration_ms - p95_duration_ms - last_run_at timeframe: type: object properties: from: type: string format: date-time description: Inclusive start. to: type: string format: date-time description: Exclusive end. timezone: type: string granularity: type: string enum: - hour - day - week - month bucket_count: type: integer minimum: 0 previous: type: object properties: from: type: string format: date-time description: Inclusive start. to: type: string format: date-time description: Exclusive end. timezone: type: string granularity: type: string enum: - hour - day - week - month bucket_count: type: integer minimum: 0 required: - from - to - timezone - granularity - bucket_count required: - from - to - timezone - granularity - bucket_count series: type: array items: type: object properties: runs: type: number completed_runs: type: number failed_runs: type: number bucket_start: type: string groups: type: array items: type: object properties: runs: type: number completed_runs: type: number failed_runs: type: number dimensions: type: object properties: project_id: type: - string - 'null' format: uuid required: - project_id required: - runs - completed_runs - failed_runs - dimensions required: - runs - completed_runs - failed_runs - bucket_start statuses: type: array items: type: object properties: status: type: string description: Status or outcome label. count: type: number description: Number of matching records. required: - status - count models: type: array items: type: object properties: provider: type: string description: AI provider. model: type: string description: AI model identifier. count: type: number description: Number of uses. required: - provider - model - count tools: type: array items: type: object properties: name: type: string description: Recorded waiting tool name. count: type: number description: Runs with this recorded waiting tool. required: - name - count projects: type: array items: type: object properties: project_id: type: - string - 'null' format: uuid description: Project ID, or null for unscoped usage. project_name: type: string description: Project display name. project_slug: type: - string - 'null' description: Project slug, or null when unavailable. count: type: number description: Number of matching records. required: - project_id - project_name - project_slug - count recent_runs: type: array items: $ref: '#/components/schemas/Run' required: - summary - timeframe - series - statuses - models - tools - projects - recent_runs Problem: type: object properties: cause: type: string enum: - schedule_concurrency_forbidden - schedule_fire_in_progress - schedule_run_limit_reached description: Schedule admission refusal. idempotency: type: object properties: state: type: string enum: - in_progress - payload_mismatch - outcome_unknown operation: type: string minLength: 1 retryable: type: boolean retry_after_seconds: type: - integer - 'null' minimum: 0 expires_at: type: - string - 'null' recovery: type: object properties: available: type: boolean description: type: string resource_url: type: string required: - available - description required: - state - operation - retryable - retry_after_seconds - expires_at description: Replay status, retry timing, and recovery lookup. type: type: string description: URI reference identifying the problem type example: https://api.veryfront.com/errors/validation-failed title: type: string description: Short human-readable summary of the problem example: Validation Failed status: type: integer minimum: 100 maximum: 599 description: HTTP status code example: 400 code: type: string description: Stable machine-readable error code example: RUN_INVALID_INPUT detail: type: string description: Human-readable explanation specific to this occurrence example: The 'email' field must be a valid email address instance: type: string description: URI reference identifying the specific occurrence example: /projects/my-project/members slug: type: string description: Stable identifier for the problem type example: validation-failed category: type: string enum: - AUTH - RESOURCE - VALIDATION - DATABASE - SUBSCRIPTION - INTEGRATION - INTERNAL description: API error category example: VALIDATION suggestion: type: string description: Suggested action to resolve the problem example: >- Check the request body and query parameters against the API documentation. errors: type: array items: type: object properties: field: type: string description: Field path that caused the error example: email message: type: string description: Error message for this field example: Invalid email format code: type: string description: Error code for this field example: INVALID_FORMAT required: - field - message description: Detailed field-level errors for validation failures required: - type - title - status UsageQueryPreset: type: string enum: - 7d - 30d - 90d default: 30d description: >- Whole local days, defaulting to 30d. Explicit from/to bounds take precedence over preset, including SDK-supplied defaults. UsageQueryFrom: type: string format: date-time description: >- Inclusive start. Supply both from and to; these bounds take precedence over preset. UsageQueryTo: type: string format: date-time description: Exclusive end, no later than the end of today in timezone. UsageQueryTimezone: type: string default: UTC UsageQueryGranularity: type: string enum: - hour - day - week - month default: day description: UTC hours, or local calendar days, Monday-based weeks and months. UsageQueryGroupBy: type: array items: type: string enum: - project - model - api_key - member maxItems: 4 description: >- Grouping dimensions supported by this operation. Repeat the parameter or use a comma-separated list. UsageQueryCompare: type: string enum: - previous_period description: >- Compare preceding calendar months for whole-month custom ranges, local days for whole-day ranges and presets, or equal elapsed duration otherwise. Run: type: object properties: id: type: string format: uuid description: Unique run UUID. run_id: type: string minLength: 1 description: >- Public run ID that run events (metadata.run_id) and runtime tools name. Equals id for runs the server names; older runs keep their run_ ID. status: type: string enum: - pending - running - waiting - completed - failed - cancelled description: Current execution state. project_id: type: string format: uuid description: Project containing the run. target: $ref: '#/components/schemas/HistoricalRunTarget' input: description: Business input supplied when the run was created. output: description: Final business output; null until successful finalization. error: $ref: '#/components/schemas/RunFailure' title: type: string description: Display title, omitted when unset. labels: $ref: '#/components/schemas/RunLabels' parent_run_id: type: string format: uuid description: Immediate parent run ID, present on child runs. root_run_id: type: string format: uuid description: Top-level ancestor run ID, present on child runs. created_at: type: string format: date-time description: When the run was accepted. updated_at: type: string format: date-time description: When the resource last changed, including usage updates. started_at: type: string format: date-time description: When the first execution attempt started, omitted before execution. finished_at: type: string format: date-time description: When the run completed, failed or was cancelled. config: type: object additionalProperties: description: A JSON value. description: Definition-specific execution configuration. execution: type: object properties: id: type: string format: uuid description: >- Current or final execution assignment identity; absent before assignment or when unavailable. runtime_instance: type: object properties: id: type: string format: uuid description: Actual executing process identity. name: type: string description: Process name captured for this execution. mode: type: string enum: - service - worker required: - id - mode description: >- Actual process attribution; additive compatibility bridge while runtime retains logical selection. runtime: $ref: '#/components/schemas/RunRuntime' timeout_seconds: type: integer exclusiveMinimum: 0 description: >- Deadline for the whole run in seconds, measured from its first start and including retries. retry_limit: type: integer minimum: 0 description: >- Maximum retries after the first attempt; only retryable failures are retried. attempt: type: integer minimum: 1 description: >- Current or last execution attempt, starting at 1; absent before execution. exit_code: type: - integer - 'null' description: >- Runtime process exit code, or null when no exit code was recorded. duration_ms: type: - integer - 'null' minimum: 0 description: >- Elapsed time from first start to finish, including waits and retries; null when not finished. format: int64 tool_error_count: type: integer minimum: 0 description: Recorded failed tool invocations during this run. logs: type: string description: Captured runtime text logs, when available. start_mode: type: string description: Recorded execution start mode, when available. worker: type: object properties: id: type: string format: uuid description: Agent worker ID. name: type: string description: >- Worker display name, omitted when the worker registered without one. worker_key: type: string description: >- Key the worker registered under, unique per project and kind; omitted when the worker is gone. implementation_kind: type: string description: >- Agent implementation the worker runs, such as codex; omitted when the worker is gone. claimed_at: type: string format: date-time description: When the worker claimed the run. required: - id - claimed_at description: >- Agent worker that claimed and executed the run; present only on worker-executed runs. description: Resolved execution settings and diagnostics. control: type: object properties: waiting: $ref: '#/components/schemas/RunWait' pause: $ref: '#/components/schemas/RunPause' cancellation: $ref: '#/components/schemas/RunCancellation' description: Pending control requests and the current wait. task_id: type: string minLength: 1 maxLength: 200 description: Orchestration task ID, distinct from the execution definition. conversation_id: type: string format: uuid description: Conversation containing the run. input_message_id: type: string format: uuid description: Conversation message that supplied the input. output_message_id: type: string format: uuid description: Conversation message containing the result. batch_id: type: string format: uuid description: Batch containing the run. trigger: $ref: '#/components/schemas/RunTrigger' usage: $ref: '#/components/schemas/Usage' descendants: type: object properties: total: type: integer minimum: 0 description: Total descendants at every depth. active: type: integer minimum: 0 description: Descendants that are pending, running or waiting. has_failures: type: boolean description: Whether any descendant has failed. usage: allOf: - $ref: '#/components/schemas/Usage' - description: Aggregate usage of every descendant, excluding this run. x-ref-description: Aggregate usage of every descendant, excluding this run. required: - total - active - has_failures description: Counts and usage across all descendant runs, excluding this run. artifacts: type: array items: $ref: '#/components/schemas/RunArtifact' description: Files produced by the run. schemas: type: object properties: input: type: - object - 'null' properties: schema: description: >- JSON Schema captured for this run; object schemas and boolean schemas are supported. anyOf: - type: boolean - type: object additionalProperties: description: A JSON value. sha256: type: string pattern: ^[a-f0-9]{64}$ description: SHA-256 digest of the pinned schema. required: - schema - sha256 output: type: - object - 'null' properties: schema: description: >- JSON Schema captured for this run; object schemas and boolean schemas are supported. anyOf: - type: boolean - type: object additionalProperties: description: A JSON value. sha256: type: string pattern: ^[a-f0-9]{64}$ description: SHA-256 digest of the pinned schema. required: - schema - sha256 required: - input - output description: >- Pinned schemas for business input and output; null means no declared schema. metadata: type: object additionalProperties: description: A JSON value. description: Additional resource metadata. required: - id - run_id - status - project_id - target - input - output - created_at - updated_at description: >- One execution resource returned by reads, creation, updates, and lifecycle actions. Omit irrelevant fields and empty groups. Errors appear only on failure; parent/root IDs only on child runs; timestamps appear when reached. Output is null until successful finalization. allOf: - if: properties: status: enum: - failed required: - status then: required: - error else: not: required: - error - if: properties: status: enum: - completed - failed - cancelled required: - status then: required: - finished_at else: not: required: - finished_at - if: properties: status: enum: - pending - running - waiting - failed - cancelled required: - status then: properties: output: type: 'null' else: {} - if: properties: status: enum: - waiting required: - status then: required: - control properties: control: required: - waiting else: properties: control: not: required: - waiting - if: properties: control: required: - pause required: - control then: properties: status: enum: - pending - running - waiting - if: required: - trigger properties: trigger: properties: type: enum: - agent - task - workflow required: - type then: required: - parent_run_id - root_run_id - if: properties: status: const: completed required: - status then: properties: descendants: properties: active: const: 0 dependentRequired: parent_run_id: - root_run_id root_run_id: - parent_run_id HistoricalRunTarget: type: object properties: type: type: string enum: - agent - task - workflow - eval description: Execution definition type. agent_kind: type: string enum: - project description: >- Server-recorded project agent identity; absence retains legacy identity semantics. name: type: string minLength: 1 maxLength: 256 description: Display name captured at admission when available. id: type: - string - 'null' minLength: 1 maxLength: 512 pattern: ^\S+$ description: Definition ID; null when unavailable on a historical run. required: - type - id additionalProperties: false description: Execution definition; its ID may be null only on historical runs. x-ref-description: Execution definition; its ID may be null only on historical runs. RunFailure: type: object properties: code: type: string minLength: 1 maxLength: 128 description: Stable failure code. message: type: string minLength: 1 maxLength: 4000 description: Human-readable failure message. details: type: object additionalProperties: {} description: Additional failure details. required: - code - message additionalProperties: false description: Failure details, present only when the run failed. x-ref-description: Failure details, present only when the run failed. RunLabels: type: object additionalProperties: type: string maxLength: 256 description: Labels used to organize runs. maxProperties: 50 propertyNames: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z0-9_.-]+$ x-ref-description: Labels used to organize runs. RunRuntime: oneOf: - type: object properties: type: type: string enum: - main_branch description: Runtime selection kind. required: - type additionalProperties: false description: Selected main-branch deployment. - type: object properties: type: type: string enum: - environment description: Runtime selection kind. id: type: string format: uuid description: Environment UUID. required: - type - id additionalProperties: false description: Selected environment. - type: object properties: type: type: string enum: - preview_branch description: Runtime selection kind. id: type: string format: uuid description: Preview branch UUID. required: - type - id additionalProperties: false description: Selected preview branch. - type: object properties: type: type: string enum: - registered description: Runtime selection kind. id: type: string minLength: 1 maxLength: 128 description: Registered runtime identifier. required: - type - id additionalProperties: false description: Selected registered runtime. description: >- Resolved logical runtime selection; main_branch identifies the selected main-branch deployment, not a worker process. x-ref-description: >- Resolved logical runtime selection; main_branch identifies the selected main-branch deployment, not a worker process. RunWait: oneOf: - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - manual_pause description: Condition required to resume the run. required: - reason description: Waiting for manual resumption. - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - tool_result description: Condition required to resume the run. tool_call_id: type: string minLength: 1 maxLength: 128 description: Tool call awaiting a result. required: - reason - tool_call_id description: Waiting for a tool result. - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - integration_connected description: Condition required to resume the run. integration: type: string minLength: 1 maxLength: 128 description: Integration awaiting connection. required: - reason - integration description: Waiting for an integration connection. - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - approval description: Condition required to resume the run. wait_id: type: string minLength: 1 maxLength: 128 description: Durable wait identifier. node_ids: type: array items: type: string minLength: 1 maxLength: 128 minItems: 1 description: Workflow nodes awaiting approval. required: - reason - wait_id - node_ids description: Waiting for workflow approval. - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - event description: Condition required to resume the run. wait_id: type: string minLength: 1 maxLength: 128 description: Durable wait identifier. name: type: string minLength: 1 maxLength: 128 description: Event required to resume. required: - reason - wait_id - name description: Waiting for a named event. - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - input_request description: Condition required to resume the run. input_request_ids: type: array items: type: string format: uuid minItems: 1 description: Input requests awaiting responses. required: - reason - input_request_ids description: Waiting for input responses. - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - child_run description: Condition required to resume the run. dependencies: type: array items: type: object properties: run_id: type: string format: uuid description: Canonical UUID of the child run. correlation: oneOf: - type: object properties: type: type: string enum: - tool_call description: Child invocation kind. id: type: string minLength: 1 maxLength: 128 description: Tool call identifier. required: - type - id additionalProperties: false description: Child started by a tool call. - type: object properties: type: type: string enum: - workflow_node description: Child invocation kind. id: type: string minLength: 1 maxLength: 128 description: Workflow node identifier. required: - type - id additionalProperties: false description: Child started by a workflow node. required: - run_id - correlation additionalProperties: false minItems: 1 description: Child runs that must finish. required: - reason - dependencies description: Waiting for child runs. - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - timer description: Condition required to resume the run. required: - resume_at - reason description: Waiting until the scheduled resume time. description: >- The current durable wait, with only the fields required to satisfy that wait. RunPause: type: object properties: requested_at: type: string format: date-time description: Time the pause was requested. required: - requested_at additionalProperties: false description: >- When a pause was requested; control.waiting confirms when execution is paused. RunCancellation: type: object properties: requested_at: type: string format: date-time description: Time cancellation was requested. stopped_at: type: - string - 'null' format: date-time description: Time the runtime confirmed its stop; null until confirmed. required: - requested_at - stopped_at RunTrigger: oneOf: - type: object properties: type: type: string enum: - user id: type: string format: uuid required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - api_key id: type: string minLength: 1 maxLength: 128 name: type: string description: >- Display name of the API key, revoked keys included; omitted when unknown. required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - service_account id: type: string minLength: 1 maxLength: 128 required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - system id: type: string minLength: 1 maxLength: 128 required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - schedule id: type: string format: uuid required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - webhook id: type: string minLength: 1 maxLength: 128 required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - agent id: type: string minLength: 1 maxLength: 512 pattern: ^\S+$ tool_call_id: type: string minLength: 1 maxLength: 128 required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - task id: type: string minLength: 1 maxLength: 512 pattern: ^\S+$ required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - workflow id: type: string minLength: 1 maxLength: 512 pattern: ^\S+$ node_id: type: string minLength: 1 maxLength: 128 required: - type - id additionalProperties: false description: How execution was initiated. x-ref-description: How execution was initiated. Usage: type: object properties: funding: type: string enum: - managed - customer - mixed description: Recorded model funding; omitted when any call has unknown funding. tokens: $ref: '#/components/schemas/TokenUsage' cost: $ref: '#/components/schemas/Cost' model_calls: type: - integer - 'null' minimum: 0 description: Billed provider call count. format: int64 capture_status: type: string enum: - complete - partial - missing description: Token capture coverage. required: - tokens - cost - capture_status description: Usage when available; unknown measurements are null. x-ref-description: Usage when available; unknown measurements are null. RunArtifact: type: object properties: artifact_id: type: string minLength: 1 maxLength: 128 description: Immutable artifact identifier. type: type: string minLength: 1 description: Artifact kind. media_type: type: string minLength: 1 description: File media type. size_bytes: type: integer minimum: 0 description: File size in bytes. sha256: type: string pattern: ^[a-f0-9]{64}$ description: SHA-256 digest of the file. href: type: string format: uri description: Authorized artifact URL. required: - artifact_id - type - media_type - size_bytes - sha256 - href description: >- An immutable file reference authorized through the run’s project and conversation permissions. TokenUsage: type: object properties: input: type: - integer - 'null' minimum: 0 description: Input tokens excluding cache reads and writes. format: int64 output: type: - integer - 'null' minimum: 0 description: Output tokens including reasoning. format: int64 cache: type: object properties: read: type: - integer - 'null' minimum: 0 description: Tokens read from the provider cache. format: int64 write: type: - integer - 'null' minimum: 0 description: Tokens written to the provider cache. format: int64 required: - read - write reasoning: type: - integer - 'null' minimum: 0 description: Reasoning tokens included in output. format: int64 total: type: - integer - 'null' minimum: 0 description: Sum of input, output, cache-read and cache-write tokens. format: int64 required: - input - output - cache - total description: >- Input excludes cache reads/writes; output includes reasoning. Total is input + output + cache.read + cache.write. Null means unknown, never zero. Cost: type: object properties: currency: type: string enum: - EUR description: Currency of reference usage value and provider costs. status: type: string enum: - estimated - posted - unavailable description: Whether charges are estimated, posted or unavailable. provider: type: - string - 'null' pattern: ^-?\d+(\.\d{1,8})?$ description: >- Recorded provider USD cost converted to EUR at the catalog reference rate; null when unknown. platform: type: - string - 'null' pattern: ^-?\d+(\.\d{1,8})?$ description: >- Reference usage value minus estimated provider cost; null when either amount is unknown. total: type: - string - 'null' pattern: ^-?\d+(\.\d{1,8})?$ description: >- Billed credits valued at EUR 0.10 per credit, independent of subscription or purchase discounts. credits: type: - string - 'null' pattern: ^-?\d+(\.\d{1,8})?$ description: Billed credit units. required: - currency - status - provider - platform - total - credits description: >- Estimated EUR usage value before tax: total values billed credits at EUR 0.10 each; provider converts recorded USD cost at the catalog reference rate; platform is total minus provider and can be negative. These amounts are visible to authorized run readers and do not represent invoice charges or actual purchase prices. Descendants sum the same per-run amounts. Credits are exact billed units. Signed decimal strings have at most eight fractional digits. Unknown provider costs leave provider and platform null. Status is independent of token capture; unavailable requires all amounts null. Posted amounts come from the billing ledger and may change through later adjustments. allOf: - if: properties: status: enum: - unavailable required: - status then: properties: provider: type: 'null' platform: type: 'null' total: type: 'null' credits: type: 'null' else: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT or API Key description: >- Use a JWT bearer token or a Veryfront API key in the `Authorization` header. apiKeyAuth: type: apiKey in: header name: X-API-Key description: Alternative API key header for `vf__` tokens. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.