curl --request POST \
--url https://api.veryfront.com/runs/{run_id}/pause \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.veryfront.com/runs/{run_id}/pause"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.veryfront.com/runs/{run_id}/pause', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.veryfront.com/runs/{run_id}/pause",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.veryfront.com/runs/{run_id}/pause"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.veryfront.com/runs/{run_id}/pause")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.veryfront.com/runs/{run_id}/pause")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"run_id": "<string>",
"id": "<string>",
"kind": "agent",
"status": "pending",
"owner": {
"kind": "conversation",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"usage": {
"requests": 1,
"model_calls": 1,
"input_tokens": 1,
"output_tokens": 1,
"cache_creation_input_tokens": 1,
"cache_read_input_tokens": 1,
"reasoning_tokens": 1,
"total_tokens": 1,
"cost_credits": "<string>"
},
"tool_error_count": 1,
"children_failed": true,
"parent_run_id": "<string>",
"root_run_id": "<string>",
"waiting_reason": "tool",
"waiting_on": [
{
"kind": "run",
"run_id": "<string>",
"correlation": {
"kind": "tool_call",
"id": "<string>"
}
}
],
"waiting": {
"reason": "tool",
"on": [
{
"kind": "run",
"run_id": "<string>",
"correlation": {
"kind": "tool_call",
"id": "<string>"
}
}
],
"pending_approvals": [
"<string>"
],
"resume_at": "2023-11-07T05:31:56Z"
},
"cancellation": {
"requested_at": "<string>",
"stopped_at": "<string>"
},
"pause": {
"requested_at": "<string>"
},
"title": "<string>",
"target": "<string>",
"workflow_id": "<string>",
"schedule_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"batch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"runtime_target_kind": "main_branch",
"runtime_target_environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"runtime_target_branch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"error": {
"message": "<string>",
"code": "<string>"
},
"logs": "<string>",
"artifacts": [
"<unknown>"
],
"duration_ms": 123,
"exit_code": 123,
"start_mode": "<string>",
"timeout_seconds": 123,
"backoff_limit": 123,
"input_schema_sha256": "<string>",
"output_schema_sha256": "<string>",
"input_schema_hash": "<string>",
"output_schema_hash": "<string>",
"trigger": {
"kind": "manual",
"id": "<string>",
"principal": {
"kind": "system",
"id": "<string>"
}
},
"trigger_kind": "manual",
"trigger_id": "<string>",
"created_by": "<string>",
"updated_at": "<string>",
"created_at": "<string>",
"started_at": "<string>",
"completed_at": "<string>",
"metadata": "<unknown>",
"control": {
"pause": {
"requested_at": "2023-11-07T05:31:56Z"
},
"waiting": {
"reason": "manual_pause",
"resume_at": "2023-11-07T05:31:56Z"
}
},
"input": "<unknown>",
"config": "<unknown>",
"output": "<unknown>",
"trigger_principal_type": "system",
"trigger_principal_id": "<string>"
}{
"type": "https://api.veryfront.com/errors/validation-failed",
"title": "Validation Failed",
"status": 400,
"idempotency": {
"state": "in_progress",
"operation": "<string>",
"retryable": true,
"retry_after_seconds": 1,
"expires_at": "<string>",
"recovery": {
"available": true,
"description": "<string>",
"resource_url": "<string>"
}
},
"code": "RUN_INVALID_INPUT",
"detail": "The 'email' field must be a valid email address",
"instance": "/projects/my-project/members",
"slug": "validation-failed",
"category": "VALIDATION",
"suggestion": "Check the request body and query parameters against the API documentation.",
"errors": [
{
"field": "email",
"message": "Invalid email format",
"code": "INVALID_FORMAT"
}
]
}{
"type": "https://api.veryfront.com/errors/validation-failed",
"title": "Validation Failed",
"status": 400,
"idempotency": {
"state": "in_progress",
"operation": "<string>",
"retryable": true,
"retry_after_seconds": 1,
"expires_at": "<string>",
"recovery": {
"available": true,
"description": "<string>",
"resource_url": "<string>"
}
},
"code": "RUN_INVALID_INPUT",
"detail": "The 'email' field must be a valid email address",
"instance": "/projects/my-project/members",
"slug": "validation-failed",
"category": "VALIDATION",
"suggestion": "Check the request body and query parameters against the API documentation.",
"errors": [
{
"field": "email",
"message": "Invalid email format",
"code": "INVALID_FORMAT"
}
]
}{
"type": "https://api.veryfront.com/errors/validation-failed",
"title": "Validation Failed",
"status": 400,
"idempotency": {
"state": "in_progress",
"operation": "<string>",
"retryable": true,
"retry_after_seconds": 1,
"expires_at": "<string>",
"recovery": {
"available": true,
"description": "<string>",
"resource_url": "<string>"
}
},
"code": "RUN_INVALID_INPUT",
"detail": "The 'email' field must be a valid email address",
"instance": "/projects/my-project/members",
"slug": "validation-failed",
"category": "VALIDATION",
"suggestion": "Check the request body and query parameters against the API documentation.",
"errors": [
{
"field": "email",
"message": "Invalid email format",
"code": "INVALID_FORMAT"
}
]
}{
"type": "https://api.veryfront.com/errors/validation-failed",
"title": "Validation Failed",
"status": 400,
"idempotency": {
"state": "in_progress",
"operation": "<string>",
"retryable": true,
"retry_after_seconds": 1,
"expires_at": "<string>",
"recovery": {
"available": true,
"description": "<string>",
"resource_url": "<string>"
}
},
"code": "RUN_INVALID_INPUT",
"detail": "The 'email' field must be a valid email address",
"instance": "/projects/my-project/members",
"slug": "validation-failed",
"category": "VALIDATION",
"suggestion": "Check the request body and query parameters against the API documentation.",
"errors": [
{
"field": "email",
"message": "Invalid email format",
"code": "INVALID_FORMAT"
}
]
}Pause run
Asks an agent, task or workflow run to pause at its next safe boundary and returns the run. Pauses this run only, never its descendants. Requires editor access to the resource that owns the run.
202 confirms the request, not that execution stopped: run.pause.requested_at records it. A queued run pauses at once; a running one pauses when its runtime reaches a boundary, and an agent after its settled model/tool step, and a task after its atomic invocation settles or between attempts. A settled task retains its result until manual resume, without rerunning its code. A confirmed pause reads status waiting with waiting.reason manual_pause; resume it with a manual resume signal. A run that finishes first is not paused. Repeating the request changes nothing. A finished run, a run waiting for something else, or a running projectless agent returns 409 RUN_NOT_PAUSABLE. Running projectless agents cannot be paused because they have no dispatch-bound stop authority.
curl --request POST \
--url https://api.veryfront.com/runs/{run_id}/pause \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.veryfront.com/runs/{run_id}/pause"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.veryfront.com/runs/{run_id}/pause', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.veryfront.com/runs/{run_id}/pause",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.veryfront.com/runs/{run_id}/pause"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.veryfront.com/runs/{run_id}/pause")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.veryfront.com/runs/{run_id}/pause")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"run_id": "<string>",
"id": "<string>",
"kind": "agent",
"status": "pending",
"owner": {
"kind": "conversation",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"usage": {
"requests": 1,
"model_calls": 1,
"input_tokens": 1,
"output_tokens": 1,
"cache_creation_input_tokens": 1,
"cache_read_input_tokens": 1,
"reasoning_tokens": 1,
"total_tokens": 1,
"cost_credits": "<string>"
},
"tool_error_count": 1,
"children_failed": true,
"parent_run_id": "<string>",
"root_run_id": "<string>",
"waiting_reason": "tool",
"waiting_on": [
{
"kind": "run",
"run_id": "<string>",
"correlation": {
"kind": "tool_call",
"id": "<string>"
}
}
],
"waiting": {
"reason": "tool",
"on": [
{
"kind": "run",
"run_id": "<string>",
"correlation": {
"kind": "tool_call",
"id": "<string>"
}
}
],
"pending_approvals": [
"<string>"
],
"resume_at": "2023-11-07T05:31:56Z"
},
"cancellation": {
"requested_at": "<string>",
"stopped_at": "<string>"
},
"pause": {
"requested_at": "<string>"
},
"title": "<string>",
"target": "<string>",
"workflow_id": "<string>",
"schedule_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"batch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"runtime_target_kind": "main_branch",
"runtime_target_environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"runtime_target_branch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"error": {
"message": "<string>",
"code": "<string>"
},
"logs": "<string>",
"artifacts": [
"<unknown>"
],
"duration_ms": 123,
"exit_code": 123,
"start_mode": "<string>",
"timeout_seconds": 123,
"backoff_limit": 123,
"input_schema_sha256": "<string>",
"output_schema_sha256": "<string>",
"input_schema_hash": "<string>",
"output_schema_hash": "<string>",
"trigger": {
"kind": "manual",
"id": "<string>",
"principal": {
"kind": "system",
"id": "<string>"
}
},
"trigger_kind": "manual",
"trigger_id": "<string>",
"created_by": "<string>",
"updated_at": "<string>",
"created_at": "<string>",
"started_at": "<string>",
"completed_at": "<string>",
"metadata": "<unknown>",
"control": {
"pause": {
"requested_at": "2023-11-07T05:31:56Z"
},
"waiting": {
"reason": "manual_pause",
"resume_at": "2023-11-07T05:31:56Z"
}
},
"input": "<unknown>",
"config": "<unknown>",
"output": "<unknown>",
"trigger_principal_type": "system",
"trigger_principal_id": "<string>"
}{
"type": "https://api.veryfront.com/errors/validation-failed",
"title": "Validation Failed",
"status": 400,
"idempotency": {
"state": "in_progress",
"operation": "<string>",
"retryable": true,
"retry_after_seconds": 1,
"expires_at": "<string>",
"recovery": {
"available": true,
"description": "<string>",
"resource_url": "<string>"
}
},
"code": "RUN_INVALID_INPUT",
"detail": "The 'email' field must be a valid email address",
"instance": "/projects/my-project/members",
"slug": "validation-failed",
"category": "VALIDATION",
"suggestion": "Check the request body and query parameters against the API documentation.",
"errors": [
{
"field": "email",
"message": "Invalid email format",
"code": "INVALID_FORMAT"
}
]
}{
"type": "https://api.veryfront.com/errors/validation-failed",
"title": "Validation Failed",
"status": 400,
"idempotency": {
"state": "in_progress",
"operation": "<string>",
"retryable": true,
"retry_after_seconds": 1,
"expires_at": "<string>",
"recovery": {
"available": true,
"description": "<string>",
"resource_url": "<string>"
}
},
"code": "RUN_INVALID_INPUT",
"detail": "The 'email' field must be a valid email address",
"instance": "/projects/my-project/members",
"slug": "validation-failed",
"category": "VALIDATION",
"suggestion": "Check the request body and query parameters against the API documentation.",
"errors": [
{
"field": "email",
"message": "Invalid email format",
"code": "INVALID_FORMAT"
}
]
}{
"type": "https://api.veryfront.com/errors/validation-failed",
"title": "Validation Failed",
"status": 400,
"idempotency": {
"state": "in_progress",
"operation": "<string>",
"retryable": true,
"retry_after_seconds": 1,
"expires_at": "<string>",
"recovery": {
"available": true,
"description": "<string>",
"resource_url": "<string>"
}
},
"code": "RUN_INVALID_INPUT",
"detail": "The 'email' field must be a valid email address",
"instance": "/projects/my-project/members",
"slug": "validation-failed",
"category": "VALIDATION",
"suggestion": "Check the request body and query parameters against the API documentation.",
"errors": [
{
"field": "email",
"message": "Invalid email format",
"code": "INVALID_FORMAT"
}
]
}{
"type": "https://api.veryfront.com/errors/validation-failed",
"title": "Validation Failed",
"status": 400,
"idempotency": {
"state": "in_progress",
"operation": "<string>",
"retryable": true,
"retry_after_seconds": 1,
"expires_at": "<string>",
"recovery": {
"available": true,
"description": "<string>",
"resource_url": "<string>"
}
},
"code": "RUN_INVALID_INPUT",
"detail": "The 'email' field must be a valid email address",
"instance": "/projects/my-project/members",
"slug": "validation-failed",
"category": "VALIDATION",
"suggestion": "Check the request body and query parameters against the API documentation.",
"errors": [
{
"field": "email",
"message": "Invalid email format",
"code": "INVALID_FORMAT"
}
]
}Authorizations
Use a JWT bearer token or a Veryfront API key in the Authorization header.
Path Parameters
1Response
Pause requested; the run as the request left it.
1The run id. Same value as run_id, which it replaces.
1agent, workflow, task, eval pending, running, waiting, completed, failed, cancelled Show child attributes
Show child attributes
The project the run belongs to. Null only for platform runs outside a project. With conversation_id, replaces owner.
AI usage summed over the billed provider calls; token totals may undercount calls whose provider usage was not captured.
Show child attributes
Show child attributes
x >= 011tool, approval, event, input, child_run, manual_pause, null Active dependencies while waiting_reason is child_run: every listed run must finish before this run continues. Null otherwise, including runs that waited before this field existed.
Show child attributes
Show child attributes
Why the run is waiting. Null unless status is waiting. Replaces waiting_reason and waiting_on.
Show child attributes
Show child attributes
Set once the run was cancelled through POST /runs/{run_id}/cancel; null otherwise.
Show child attributes
Show child attributes
Set while a pause requested through POST /runs/{run_id}/pause governs the run: requested on a pending or running run, or confirmed as its manual_pause wait. Null otherwise.
Show child attributes
Show child attributes
The custom title set at creation with request.name; null when none was set.
main_branch, environment, preview_branch, null Why the run failed. OUTPUT_TOO_LARGE carries detail { size_bytes, limit_bytes }, and its message names both sizes.
Show child attributes
Show child attributes
Task runs only; null for other kinds. The execution deadline for the whole task run, in seconds, measured from its first started_at and spanning every attempt. At the deadline the runtime aborts ctx.signal and the run fails with error.code RUN_TIMEOUT. Task code that ignores ctx.signal can keep running inside the runtime process. Default 300; task:eval defaults to 7200.
Task runs only; null for other kinds. How many times a failed task run is retried, with exponential backoff, before it fails: at most backoff_limit + 1 attempts. Only two failures are retried: the runtime never started the task (connection refused, or HTTP 503 with the runtime RUNTIME_SHUTTING_DOWN admission refusal), or the task threw the framework RetryableError. Every other failure, and any retry whose backoff would pass the timeout_seconds deadline, fails the run at once. Default 3; task:eval defaults to 0.
Lowercase sha256 hex of the canonical JSON Schema of the declared input schema this run ran against. Null when none is declared or the run predates schema identities.
^[0-9a-f]{64}$Lowercase sha256 hex of the canonical JSON Schema of the declared output schema this run ran against. Null when none is declared or the run predates schema identities.
^[0-9a-f]{64}$The declared input schema this run ran against, as sha256:. Replaces input_schema_sha256.
^sha256:[0-9a-f]{64}$The declared output schema this run ran against, as sha256:. Replaces output_schema_sha256.
^sha256:[0-9a-f]{64}$How and by whom the run was started. Null for runs recorded without a trigger principal. Replaces trigger_kind, trigger_id and trigger_principal_*.
Show child attributes
Show child attributes
manual, schedule, webhook, api, null 1 - 255Show child attributes
Show child attributes
The final output of a completed run. Its JSON serialization is at most 1,048,576 bytes (1 MiB) of UTF-8. A larger output is never stored or truncated: the run fails with error.code OUTPUT_TOO_LARGE and output null.
system, user, api_key, service_account, null