Vertesia Interaction Runs API
The `/runs` endpoints manage interaction execution records. Every interaction execution, whether synchronous, asynchronous, conversation-based, streamed, or batch, creates a run that tracks its input, output, status, token usage, execution source, and timing. Runs are the primary audit trail for interaction activity within a project. Use these endpoints to create runs, list and search execution history, compute facets, stream progress, send tool or user messages into active runs, clone runs, and replay previous executions.
Vertesia Interaction Runs API is one of 48 APIs that Vertesia publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
This API exposes 6 JSON Schema definitions.
Tagged areas include Interaction Runs. The published artifact set on APIs.io includes an OpenAPI specification and 6 JSON Schemas.
This API exposes
7 operations
across 4 paths,
and defines 144 schemas.
It is described by OpenAPI 3.2.0, at version 1.6.0-dev.20261019.172735Z.
Requests are made against a single base URL, https://api.{region}.vertesia.io/api/v1.
The identity and technical contract details declared by the specification.
Interaction Runs 7
The /runs endpoints manage interaction execution records. Every interaction execution, whether synchronous, asynchronous, conversation-based, streamed, or batch, creates a run tha…
POST
/runs
Create a run
CreateRun
1 param
body
→ 2005004XX
GET
/runs
List runs
ListRuns
12 params
→ 2005004XX
POST
/runs/search
Search runs
SearchRuns
1 param
body
→ 2005004XX
GET
/runs/{runId}
Retrieve a run
GetRun
3 params
→ 2005004XX
PUT
/runs/{runId}
Update a run
UpdateRun
2 params
body
→ 2005004XX
DELETE
/runs/{runId}
Delete a run
DeleteRun
2 params
→ 2005004XX
GET
/runs/{runId}/stream
Stream a run
StreamRun
1 param
→ 2005004XX
PromptSegmentDefType
string
BedrockMistralOptions
object
8 properties
InteractionExecutionConfiguration
object
14 properties
InferenceProfile
object
A reusable environment, model and inference parameter preset. Credentials remain in the environment.
5 properties
1 required
DeleteByIdResult
object
1 property
1 required
ModelSource
string
Source of the resolved model configuration
OpenAiGptImageOptions
object
12 properties
UserChannel
object
1 required
AsyncCompletionMode
string
TwelvelabsPegasusOptions
object
4 properties
OpenAiTranscriptionOptions
object
2 properties
FacetSpec
object
2 properties
2 required
RunDataStorageLevel
string
ExecutionRunRef
object
30 properties
12 required
ImageResult
object
2 properties
2 required
BedrockMantleClaudeOptions
object
12 properties
ExecutionEnvironmentRef
object
12 properties
8 required
VertexAIGeminiOptions
object
27 properties
EmailChannel
object
Email channel configuration with threading support. Used for email-based agent communication.
6 properties
2 required
ExecutionRunDocRef
object
The run ref is used to identify a run document in the storage
3 properties
3 required
OpenAiImageGenerationOptions
object
12 properties
1 required
TextArtifactReference
object
Reference to text content externalized to agent artifact storage.
6 properties
6 required
VertexAIClaudeOptions
object
12 properties
WorkflowAncestor
object
3 properties
3 required
SortOption
object
2 properties
1 required
XAIGrokImageOptions
object
6 properties
UsedSkill
object
Skill metadata tracked when a skill is used
5 properties
2 required
PromptSegmentRef_PromptTemplateRef
object
4 properties
2 required
VertexAIGeminiOmniVideoOptions
object
5 properties
BedrockGptOssOptions
object
9 properties
AgentResourceAction
string
ToolResult
object
8 properties
3 required
UpdateExecutionRunPayload
object
27 properties
OpenAiAudioOptions
object
3 properties
BedrockPalmyraOptions
object
10 properties
ToolReference
object
Lightweight tool reference for activity payloads. References tools stored in GCP instead of embedding full tool definitions.
3 properties
3 required
InCodePrompt
object
6 properties
3 required
AgentResourceReference
object
A navigable reference to a resource an agent tool mutated. Tools return these as tool-result metadata (see {@link ToolResultMeta.resources } ); the conversatio…
5 properties
4 required
JSONSchemaProperties
object
BedrockConverseOptions
object
10 properties
VertexAIGrokOptions
object
5 properties
AudioResult
object
9 properties
3 required
AgentResourceType
string
The kinds of Vertesia resource an agent tool can report having created, updated, or deleted. Restricted to resources that have a real detail route to navigate…
ThoughtsResult
object
2 properties
2 required
AsyncCompletionOptions
object
Options for async completion and/or streaming LLM responses
10 properties
1 required
InferenceProfileSnapshot
object
The selected profile and content revision at execution creation. Effective overrides are recorded in the execution config.
5 properties
4 required
InteractionRef
object
13 properties
7 required
ToolApprovalGrant
object
4 properties
3 required
InteractiveChannel
object
Interactive (UI chat) channel configuration. Used for real-time chat interface communication.
1 property
1 required
JSONSchema
object
9 properties
ExecutionRunInteraction
Interaction reference. Stored interactions may be populated as full Interaction documents; in-code interactions are represented as refs whose id is the namespa…
RunSearchQuery
object
22 properties
JsonResult
object
2 properties
2 required
AIModel
object
16 properties
3 required
BedrockAI21Options
object
9 properties
LlmCallType
string
Types of LLM calls in a conversation
GroqOptions
object
8 properties
1 required
BedrockCohereCommandOptions
object
10 properties
ResolvedRuntimeConfig
object
Resolved runtime configuration for an interaction
5 properties
2 required
RunSearchPayload
object
10 properties
StatelessExecutionOptions
object
10 properties
1 required
OpenAiImageGenerationMask
object
2 properties
CompletionResult
object
1 required
AzureFoundryChatOptions
object
10 properties
BedrockMantleResponsesOptions
object
9 properties
PendingToolApprovalResults
object
4 properties
4 required
BedrockMantleChatCompletionsOptions
object
8 properties
ResolvedInteractionExecutionInfo
object
Resolved execution info for an interaction. Contains the interaction ID, basic metadata, and the resolved runtime configuration (environment, model) that would…
7 properties
6 required
ProjectRef
object
4 properties
3 required
AgentCheckpointConfiguration
object
2 properties
ResolvedEnvironmentInfo
object
Resolved environment information
3 properties
3 required
OpenRouterTextOptions
object
23 properties
InteractionVisibility
string
SchemaRef
object
Schema can be stored or specified as a reference to an external schema. We only support "store:" references for now
1 property
1 required
AgentBudgetConfiguration
object
Weighted token budget for an agent run and its subagent workstreams. A call is charged output × outputtokenweight + uncached input × inputtokenweight + cached…
8 properties
ExternalizedToolInputRefs
object
ExecutionRunStatus
string
OpenAiDalleOptions
object
6 properties
HttpTimeoutOptions
object
HTTP timeouts applied to a driver's upstream LLM-provider calls. All values are in milliseconds. Drivers should map these onto whatever HTTP client their SDK u…
4 properties
BedrockClaudeOptions
object
13 properties
MistralTextOptions
object
14 properties
OpenAiThinkingOptions
object
12 properties
InferenceProfileName
string
Editable display name, independent of the stable profile ID.
AgentSearchScope
string
Defines the scope for agent search operations.
ServerSentEventsResponse
string
OpenAiSpeechOptions
object
5 properties
ToolUse
object
A tool use instance represents a call to a tool. The id property is used to identify the tool call.
4 properties
3 required
RunCreatePayload
object
Interaction execution payload for creating a new run It uses interaction field (from NamedInteractionExecutionPayload) to pass the interaction ID to run
12 properties
1 required
ToolDefinition
object
Tool definition for LLM tool use. The inputschema uses a permissive type to support both: - AJV's JSONSchemaType for type-safe schema generation - Plain object…
3 properties
2 required
ConversationState
object
Conversation state passed between workflow activities: the activity-safe, per-turn dynamic subset of a multi-turn agent conversation. Rides every conversation…
42 properties
5 required
AnthropicClaudeOptions
object
13 properties
ExecutionRunRefArray
array
BedrockNovaOptions
object
9 properties
ExecutionRunWorkflow
object
5 properties
2 required
InteractionExecutionResult
object
33 properties
14 required
NovaCanvasOptions
object
13 properties
1 required
VideoResult
object
2 properties
2 required
TextFallbackOptions
object
10 properties
AgentToolApprovalMode
string
StreamingTelemetryContext
object
Telemetry context for streaming mode. Contains info not available in currentstate needed to send LlmCallEvent.
3 properties
2 required
AccountRef
object
2 properties
2 required
StreamingOptions
object
Streaming-specific options (only needed when stream=true)
2 properties
1 required
RunSource
object
5 properties
5 required
ConversationStripOptions
object
Configuration for stripping large data from conversation history to prevent JSON serialization issues and reduce storage bloat.
3 properties
ImagenOptions
object
19 properties
InferenceProfileId
string
MongoDB ObjectId of the inference profile.
Plan
object
2 properties
1 required
PendingMcpConnection
object
An MCP server the user can connect to but hasn't yet (active + accessible, no OAuth token). Built at tool-discovery time and stored on the conversation state s…
5 properties
3 required
ToolResultMeta
object
Metadata a tool executor may attach to its result. Kept as an open record for forward compatibility while typing the fields the runtime interprets.
1 property
ResultStorageOptions
object
Options for storing inference results to cloud storage
1 property
1 required
PlanTask
object
5 properties
2 required
SupportedProviders
string
ExecutionTokenUsage
object
9 properties
ExecutionRun
object
30 properties
14 required
SkillContextTriggers
object
Context triggers for auto-injection of skills. When these conditions match, the skill is automatically injected into the agent context.
3 properties
ErrorResponse
object
Standard JSON error response returned by the server error handler.
5 properties
2 required
AgentRunnerOptions
object
Configuration options for Agent Runner functionality. These options control how interactions are exposed and executed in the Agent Runner.
11 properties
TextResult
object
2 properties
2 required
PromptCacheDiagnostic
object
Safe diagnostic for one provider-side explicit prompt-cache attempt. It never contains prompt contents, images, credentials, or full provider resource names.
9 properties
4 required
PromptTemplateRef
object
10 properties
7 required
OpenAiTextOptions
object
16 properties
ToolApprovalGrantMap
object
ExternalizedToolInputRef
object
Sidecar metadata for generated tool input fields that were stored outside model-visible toolinput. Keyed by tooluse.id on ConversationState.
3 properties
3 required
InteractionExecutionError
object
5 properties
2 required
The full machine-readable OpenAPI contract behind this narrative.
Other APIs Vertesia publishes across the network.
