> ## 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 run analytics > Return run analytics for the authorized account using a human user session. Requires account.billing.read. ## OpenAPI ````yaml /cloud/rest/openapi.json get /account/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) | Access models and inference. | | [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: Access models and inference. - 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/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: 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/Search - name: knowledge/Search/Search - name: knowledge/Embeddings - name: knowledge/Embeddings/Project embeddings - name: deployments/Releases - name: deployments/Releases/Releases - name: deployments/Releases/Release Versions - 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/Environments/Project Domains - name: runtime/Environments/Environment Variable Keys - name: runtime/Servers - name: runtime/Servers/Environment Servers - name: runtime/Servers/Project servers - 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: runtime/Cache/User 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 users - 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/Permissions - name: identity-access/Permissions/Feature gates - name: identity-access/Permissions/Project Ownership - 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/Subscriptions - name: billing-usage/Subscriptions/Seats - name: billing-usage/Billing - name: billing-usage/Billing/Invoices - name: billing-usage/Billing/Payments - name: billing-usage/Billing/Payment Methods - name: billing-usage/Billing/Billing Details - name: billing-usage/Billing/Account billing - name: billing-usage/Credits - name: billing-usage/Credits/Credits - name: billing-usage/Budgets - name: billing-usage/Budgets/Budgets - name: billing-usage/Usage - name: billing-usage/Usage/API key usage - name: billing-usage/Usage/Account 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: /account/analytics/runs: get: tags: - billing-usage/Analytics/Run Analytics summary: Get run analytics description: >- Return run analytics for the authorized account using a human user session. Requires account.billing.read. operationId: getAccountRunAnalytics parameters: - schema: type: string enum: - 7d - 30d - 90d default: 30d description: Relative timeframe preset. required: false description: Relative timeframe preset. name: preset in: query - schema: type: string default: UTC description: IANA timezone for daily bucket boundaries. required: false description: IANA timezone for daily bucket boundaries. name: timezone in: query - schema: type: - array - 'null' items: type: string description: >- Project label filters as key or key=value, repeated or comma-separated. 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: Account run analytics statistics. content: application/json: schema: $ref: '#/components/schemas/RunAnalytics' examples: example: summary: Example response value: summary: total_runs: 0 completed_runs: 0 failed_runs: 0 average_duration_ms: null p95_duration_ms: null last_run_at: null timeframe: from: '2026-10-01T00:00:00Z' to: '2026-10-02T00:00:00Z' granularity: day timezone: UTC bucket_count: 1 series: [] statuses: [] models: [] tools: [] projects: [] recent_runs: [] '400': description: Bad request content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/TargetRunProblem' - properties: status: const: 400 '401': description: Unauthorized content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/TargetRunProblem' - properties: status: const: 401 '403': description: Forbidden content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/TargetRunProblem' - properties: status: const: 403 '404': description: Not found content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/TargetRunProblem' - properties: status: const: 404 '429': description: Rate limit exceeded headers: Retry-After: schema: type: integer format: int32 minimum: 1 content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/TargetRunProblem' - properties: status: const: 429 '500': description: Server error content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/TargetRunProblem' - properties: status: const: 500 components: schemas: RunAnalytics: type: object properties: summary: type: object properties: total_runs: type: number description: Total agent runs in the timeframe. completed_runs: type: number description: Completed runs in the timeframe. failed_runs: type: number description: Failed runs in the timeframe. average_duration_ms: type: - number - 'null' description: Average 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: Most recent run creation timestamp. required: - total_runs - completed_runs - failed_runs - average_duration_ms - p95_duration_ms - last_run_at timeframe: type: object properties: from: type: string description: Inclusive timeframe start timestamp. to: type: string description: Exclusive timeframe end timestamp. granularity: type: string enum: - day description: Analytics aggregation granularity. timezone: type: string description: IANA timezone used for buckets. bucket_count: type: number description: Number of buckets returned. required: - from - to - granularity - timezone - bucket_count series: type: array items: type: object properties: bucket_start: type: string description: Bucket start timestamp. runs: type: number description: Runs created in the bucket. completed_runs: type: number description: Completed runs in the bucket. failed_runs: type: number description: Failed runs in the bucket. required: - bucket_start - runs - completed_runs - failed_runs 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 TargetRunProblem: type: object properties: type: type: string description: Problem type URI reference. title: type: string status: type: integer minimum: 400 maximum: 599 format: int64 code: type: string minLength: 1 maxLength: 128 cause: type: string enum: - schedule_concurrency_forbidden - schedule_fire_in_progress - schedule_run_limit_reached description: Schedule admission refusal. detail: type: string instance: type: string errors: type: array items: type: object properties: field: type: string message: type: string required: - field - message required: - type - title - status - code Run: type: object properties: id: type: string format: uuid description: Unique run UUID. 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: 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. 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: anyOf: - type: boolean - type: object additionalProperties: description: A JSON value. description: >- JSON Schema captured for this run; object schemas and boolean schemas are supported. 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: anyOf: - type: boolean - type: object additionalProperties: description: A JSON value. description: >- JSON Schema captured for this run; object schemas and boolean schemas are supported. 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 - 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. 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 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: 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.