Skip to main content
PATCH
Request JSON

Authorizations

Authorization
string
header
required

Use a JWT bearer token or a Veryfront API key in the Authorization header.

Headers

If-Match
string
required

Path Parameters

run_id
string<uuid>
required

Run to update. Conversation-owned runs also require editor access on the conversation. Run-scoped credentials cannot update runs.

Body

application/json

Update the run title or labels.

title
string | null

Replace the display title; null clears it.

Required string length: 1 - 255
labels
object

Replace the complete label map; an empty object clears it.

Response

Updated run resource

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.

id
string<uuid>
required

Unique run UUID.

status
enum<string>
required

Current execution state.

Available options:
pending,
running,
waiting,
completed,
failed,
cancelled
project_id
string<uuid>
required

Project containing the run.

target
object
required

Execution definition; its ID may be null only on historical runs.

input
any
required

Business input supplied when the run was created.

output
any
required

Final business output; null until successful finalization.

created_at
string<date-time>
required

When the run was accepted.

updated_at
string<date-time>
required

When the resource last changed, including usage updates.

error
object

Failure details, present only when the run failed.

title
string

Display title, omitted when unset.

labels
object

Labels used to organize runs.

parent_run_id
string<uuid>

Immediate parent run ID, present on child runs.

root_run_id
string<uuid>

Top-level ancestor run ID, present on child runs.

started_at
string<date-time>

When the first execution attempt started, omitted before execution.

finished_at
string<date-time>

When the run completed, failed or was cancelled.

config
object

Definition-specific execution configuration.

execution
object

Resolved execution settings and diagnostics.

control
object

Pending control requests and the current wait.

task_id
string

Orchestration task ID, distinct from the execution definition.

Required string length: 1 - 200
conversation_id
string<uuid>

Conversation containing the run.

input_message_id
string<uuid>

Conversation message that supplied the input.

output_message_id
string<uuid>

Conversation message containing the result.

batch_id
string<uuid>

Batch containing the run.

trigger
object

How execution was initiated.

usage
object

Usage when available; unknown measurements are null.

descendants
object

Counts and usage across all descendant runs, excluding this run.

artifacts
object[]

Files produced by the run.

schemas
object

Pinned schemas for business input and output; null means no declared schema.

metadata
object

Additional resource metadata.