Skip to main content
POST
/
conversations
/
{conversation_id}
/
agent-runs
/
{run_id}
/
complete
Finalize a durable agent run
curl --request POST \
  --url https://api.veryfront.com/conversations/{conversation_id}/agent-runs/{run_id}/complete \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "completed",
  "metadata": {
    "provider": "<string>",
    "model": "<string>",
    "inputTokens": 123,
    "outputTokens": 123,
    "finishReason": "<string>",
    "cachedInputTokens": 123,
    "reasoningTokens": 123,
    "providerRequestId": "<string>"
  },
  "terminal_error_code": "<string>",
  "terminal_error_message": "<string>"
}
'
{
  "run_id": "<string>",
  "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requested_by_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "<string>",
  "status": "completed",
  "runtime_target_kind": "production",
  "latest_event_id": 1,
  "created_at": "<string>",
  "source_target_kind": "project",
  "source_target_environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "source_target_branch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "runtime_target_environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "runtime_target_branch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "parent_conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "parent_run_id": "<string>",
  "spawned_from_message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "spawned_from_tool_call_id": "<string>",
  "input_anchor_message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "handoff_message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "resolved_deployment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "waiting_tool_call_id": "<string>",
  "waiting_tool_name": "<string>",
  "terminal_error_code": "<string>",
  "terminal_error_message": "<string>",
  "started_at": "<string>",
  "finished_at": "<string>"
}

Authorizations

​
Authorization
string
header
required

Authentication via JWT token or API key. JWT: Get from Veryfront dashboard. API Key: Format "vf__" - create via /api-keys endpoint.

Path Parameters

​
conversation_id
string<uuid>
required
​
run_id
string
required
Minimum string length: 1

Body

application/json
​
status
enum<string>
required
Available options:
completed,
failed,
cancelled
​
metadata
object
​
terminal_error_code
string | null
​
terminal_error_message
string | null

Response

200 - application/json

Finalized run

​
run_id
string
required
Minimum string length: 1
​
conversation_id
string<uuid>
required
​
message_id
string<uuid>
required
​
project_id
string<uuid> | null
required
​
requested_by_user_id
string<uuid>
required
​
agent_id
string
required
Required string length: 1 - 128
​
status
required
Available options:
completed,
failed,
cancelled
​
runtime_target_kind
enum<string> | null
required
Available options:
production,
environment,
preview_branch
​
latest_event_id
integer
required
Required range: x >= 0
​
created_at
string
required
​
source_target_kind
enum<string> | null
Available options:
project,
production,
environment,
preview_branch
​
source_target_environment_id
string<uuid> | null
​
source_target_branch_id
string<uuid> | null
​
runtime_target_environment_id
string<uuid> | null
​
runtime_target_branch_id
string<uuid> | null
​
parent_conversation_id
string<uuid> | null
​
parent_run_id
string | null
Minimum string length: 1
​
spawned_from_message_id
string<uuid> | null
​
spawned_from_tool_call_id
string | null
Required string length: 1 - 128
​
input_anchor_message_id
string<uuid> | null
​
handoff_message_id
string<uuid> | null
​
resolved_deployment_id
string<uuid> | null
​
waiting_tool_call_id
string | null
Required string length: 1 - 128
​
waiting_tool_name
string | null
​
terminal_error_code
string | null
​
terminal_error_message
string | null
​
started_at
string | null
​
finished_at
string | null