Agent Runs

The Agent Runs API is the canonical way to start and manage conversation agents. Each agent run gets a stable identity (MongoDB document) with its own ID, lifecycle tracking, artifact storage, and Elasticsearch indexing.

For non-conversation asynchronous interaction execution (webhooks, batch processing), continue using the /execute/async endpoint.

Base path: /api/v1/agents

Create Agent Run

Creates a new agent run and starts a conversation workflow.

Endpoint: /agents

Method: POST

Requirements: User must have workflow:run permission.

Headers

Input Parameters

Example Request

{
  "interaction": "MyAgent",
  "data": {
    "task": "Analyze the Q4 report"
  },
  "environment": "<ENVIRONMENT_ID>",
  "model": "<MODEL_ID>",
  "interactive": true,
  "tags": ["analysis"]
}

Example Response

{
  "id": "6801a3f2e4b0d1234abcdef0",
  "account": "...",
  "project": "...",
  "interaction": "MyAgent",
  "data": { "task": "Analyze the Q4 report" },
  "environment": "default",
  "model": "claude-sonnet-4-6",
  "interactive": true,
  "status": "running",
  "started_at": "2025-04-17T10:30:00.000Z",
  "started_by": "user:abc123",
  "tags": ["analysis"],
  "visibility": "project",
  "created_at": "2025-04-17T10:30:00.000Z",
  "updated_at": "2025-04-17T10:30:00.000Z"
}

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "interaction": "MyAgent",
    "data": { "task": "Analyze the Q4 report" },
    "environment": "<ENVIRONMENT_ID>",
    "model": "<MODEL_ID>",
    "interactive": true
  }'

Retrieve Agent Run

Get an agent run by its stable ID.

Endpoint: /agents/<AGENT_RUN_ID>

Method: GET

Requirements: User must have workflow:run permission. Private runs are only visible to the owner or superadmin.

Headers

Path Parameters

Example Response

{
  "id": "6801a3f2e4b0d1234abcdef0",
  "account": "...",
  "project": "...",
  "interaction": "MyAgent",
  "status": "running",
  "interactive": true,
  "started_at": "2025-04-17T10:30:00.000Z",
  "started_by": "user:abc123",
  "visibility": "project",
  "created_at": "2025-04-17T10:30:00.000Z",
  "updated_at": "2025-04-17T10:30:00.000Z"
}

Code Examples

curl -X GET 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

List Agent Runs

List agent runs with optional filters. Non-superadmin users see project-visible runs and their own private runs.

Endpoint: /agents

Method: GET

Requirements: User must have workflow:run permission.

Headers

Query Parameters

Example Response

[
  {
    "id": "6801a3f2e4b0d1234abcdef0",
    "interaction": "MyAgent",
    "status": "running",
    "interactive": true,
    "started_at": "2025-04-17T10:30:00.000Z",
    "started_by": "user:abc123",
    "visibility": "project"
  },
  {
    "id": "6801a3f2e4b0d1234abcdef1",
    "interaction": "MyAgent",
    "status": "completed",
    "interactive": false,
    "started_at": "2025-04-17T09:00:00.000Z",
    "started_by": "user:abc123",
    "visibility": "project"
  }
]

Code Examples

curl -X GET 'https://api.vertesia.io/api/v1/agents?status=running&limit=10' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Search Agent Runs

Full-text search over agent runs using Elasticsearch. Searches across titles, topics, and content.

Endpoint: /agents/search

Method: GET

Requirements: User must have workflow:run permission.

Headers

Query Parameters

Example Response

{
  "hits": [
    {
      "id": "6801a3f2e4b0d1234abcdef0",
      "score": 1.5,
      "interaction": "MyAgent",
      "status": "completed",
      "started_at": "2025-04-17T10:30:00.000Z",
      "started_by": "user:abc123",
      "title": "Q4 Report Analysis",
      "topic": "Financial analysis"
    }
  ],
  "total": 1
}

Code Examples

curl -X GET 'https://api.vertesia.io/api/v1/agents/search?query=Q4+report&status=completed' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Terminate Agent Run

Cancel a running agent. The workflow is cancelled and the agent run status is set to cancelled.

Endpoint: /agents/<AGENT_RUN_ID>

Method: DELETE

Requirements: User must have workflow:run permission.

Headers

Path Parameters

Query Parameters

Example Response

{
  "message": "Agent run terminated",
  "reason": "No longer needed"
}

Code Examples

curl -X DELETE 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>?reason=No+longer+needed' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Restart Agent Run

Restart a completed, failed, or cancelled agent run. This continues the same AgentRun — a new workflow is started that loads the conversation history from where it left off.

Endpoint: /agents/<AGENT_RUN_ID>/restart

Method: POST

Requirements: User must have workflow:run permission. The run must not be in running or created status.

Headers

Path Parameters

Example Response

{
  "id": "6801a3f2e4b0d1234abcdef0",
  "status": "running",
  "started_at": "2025-04-17T11:00:00.000Z",
  "updated_at": "2025-04-17T11:00:00.000Z"
}

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>/restart' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Fork Agent Run

Fork a conversation into a new agent run. The new run loads conversation history from the source but has its own identity, stream, and artifacts.

Endpoint: /agents/<AGENT_RUN_ID>/fork

Method: POST

Requirements: User must have workflow:run permission.

Headers

Path Parameters

Example Response

{
  "id": "6801a3f2e4b0d1234abcdef1",
  "interaction": "MyAgent",
  "status": "running",
  "started_at": "2025-04-17T11:00:00.000Z",
  "visibility": "project"
}

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>/fork' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Send Signal

Send a signal to a running agent workflow. Signals allow external systems or users to send information to a running workflow.

Endpoint: /agents/<AGENT_RUN_ID>/signal/<SIGNAL_NAME>

Method: POST

Requirements: User must have workflow:run permission.

Headers

Path Parameters

Input Parameters

The payload depends on the signal type:

Example Request

{
  "message": "Please also include a summary"
}

Example Response

{
  "status": "success",
  "message": "Signal UserInput sent"
}

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>/signal/UserInput' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Please also include a summary"
  }'

Query Agent State

Query a running agent's internal state. Queries are synchronous and return data immediately without affecting execution.

Endpoint: /agents/<AGENT_RUN_ID>/query/<QUERY_NAME>

Method: GET

Requirements: User must have workflow:run permission.

Headers

Path Parameters

Example Response (for ActiveWorkstreams query)

{
  "workstreams": [
    {
      "id": "ws-1",
      "name": "Research",
      "status": "active"
    }
  ]
}

Error Responses

Code Examples

curl -X GET 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>/query/ActiveWorkstreams' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Stream Messages

Stream real-time messages from an agent run via Server-Sent Events (SSE). The SDK handles historical message fetch followed by SSE connection automatically with reconnection logic.

Endpoint: /agents/<AGENT_RUN_ID>/stream

Method: GET (SSE)

Requirements: User must have workflow:run permission.

Headers

Path Parameters

Query Parameters

Response Type: Server-Sent Events (SSE) stream

Code Examples

curl -X GET 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>/stream?since=0' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Retrieve Messages

Get stored messages for an agent run.

Endpoint: /agents/<AGENT_RUN_ID>/updates

Method: GET

Requirements: User must have workflow:run permission.

Headers

Path Parameters

Query Parameters

Example Response

{
  "messages": [
    {
      "ts": 1713349800000,
      "t": "UPDATE",
      "m": "Analyzing the Q4 report...",
      "wri": "<WORKFLOW_RUN_ID>"
    },
    {
      "ts": 1713349810000,
      "t": "COMPLETE",
      "m": "Analysis complete.",
      "wri": "<WORKFLOW_RUN_ID>"
    }
  ]
}

Code Examples

curl -X GET 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>/updates?since=0' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Post Update

Post a message to an agent run's update stream. This is primarily intended for internal workflow execution logic to publish progress messages.

Endpoint: /agents/<AGENT_RUN_ID>/updates

Method: POST

Requirements: User must have workflow:run permission.

Headers

Path Parameters

Input Parameters

Example Request

{
  "type": "PROGRESS",
  "message": "Processing step 2 of 5",
  "details": { "current": 2, "total": 5 }
}

Example Response

{
  "success": true
}

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>/updates' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "PROGRESS",
    "message": "Processing step 2 of 5"
  }'

Artifacts

Agent runs have dedicated artifact storage for files produced during execution.

List Artifacts

Endpoint: /agents/<AGENT_RUN_ID>/artifacts

Method: GET

Requirements: User must have workflow:run permission.

Headers

Path Parameters

Example Response

["report.pdf", "data.csv", "chart.png"]

Get Artifact

Endpoint: /agents/<AGENT_RUN_ID>/artifacts/<PATH>

Method: GET

Requirements: User must have workflow:run permission.

Path Parameters

Query Parameters

Upload Artifact

Endpoint: /agents/<AGENT_RUN_ID>/artifacts/<PATH>

Method: PUT

Requirements: User must have workflow:run permission.

Headers

Code Examples

# List artifacts
curl -X GET 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>/artifacts' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

# Get download URL
curl -X GET 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>/artifacts/report.pdf?url=1&disposition=inline' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Get Internals

Get internal details for an agent run, including workflow IDs and artifact paths. Useful for debugging and advanced observability.

Endpoint: /agents/<AGENT_RUN_ID>/internals

Method: GET

Requirements: User must have workflow:run permission.

Headers

Path Parameters

Example Response

{
  "id": "6801a3f2e4b0d1234abcdef0",
  "workflow_id": "AgentRun:6801a3f2e4b0d1234abcdef0",
  "first_workflow_run_id": "<WORKFLOW_RUN_ID>",
  "artifacts_path": "agent-runs/6801a3f2e4b0d1234abcdef0",
  "status": "running",
  "interaction": "MyAgent",
  "interactive": true,
  "started_at": "2025-04-17T10:30:00.000Z",
  "started_by": "user:abc123"
}

Code Examples

curl -X GET 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>/internals' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Get Run Details

Get detailed workflow execution information, including status, duration, input/output, and optionally the full execution history.

Endpoint: /agents/<AGENT_RUN_ID>/details

Method: GET

Requirements: User must have workflow:run permission.

Headers

Path Parameters

Query Parameters

Example Response

{
  "status": "COMPLETED",
  "started_at": "2025-04-17T10:30:00.000Z",
  "closed_at": "2025-04-17T10:31:00.000Z",
  "execution_duration": 60,
  "run_id": "<WORKFLOW_RUN_ID>",
  "workflow_id": "AgentRun:6801a3f2e4b0d1234abcdef0",
  "type": "ExecuteConversationWorkflow",
  "input": { "task": "Analyze the Q4 report" },
  "result": { "success": true },
  "pendingActivities": [],
  "error": null
}

Code Examples

curl -X GET 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>/details?include_history=true' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

List Child Workflows

List child workflows spawned by an agent run (e.g. sub-agents, attachment processing).

Endpoint: /agents/<AGENT_RUN_ID>/children

Method: GET

Requirements: User must have workflow:run permission.

Headers

Path Parameters

Example Response

{
  "runs": [
    {
      "run_id": "<CHILD_RUN_ID>",
      "workflow_id": "attachments:AgentRun:6801a3f2e4b0d1234abcdef0",
      "status": "COMPLETED",
      "started_at": "2025-04-17T10:30:05.000Z",
      "closed_at": "2025-04-17T10:30:15.000Z",
      "type": "ProcessAttachmentsWorkflow"
    }
  ]
}

Code Examples

curl -X GET 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>/children' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

AgentRun Object

The AgentRun object returned by all endpoints:

Ingest Telemetry Events

Ingest telemetry events for an agent run. Workers use this endpoint to send telemetry data for analytics.

Endpoint: /agents/<AGENT_RUN_ID>/events

Method: POST

Requirements: User must have workflow:run permission.

Headers

Path Parameters

Input Parameters

AgentEvent Types

AgentEvent is a union of several event types. All events share a common base structure:

BaseAgentEvent Fields

LlmCallEvent Fields

Extends BaseAgentEvent with LLM-specific metrics:

ToolCallEvent Fields

Extends BaseAgentEvent with tool execution metrics:

Example Request

curl -X POST 'https://api.vertesia.io/api/v1/agents/<AGENT_RUN_ID>/events' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      {
        "eventType": "llm_call",
        "timestamp": "2025-01-15T10:30:00Z",
        "runId": "<WORKFLOW_RUN_ID>",
        "model": "claude-sonnet-4-6",
        "environmentId": "<ENVIRONMENT_ID>",
        "environmentType": "bedrock",
        "interactionId": "<INTERACTION_ID>",
        "promptTokens": 1500,
        "completionTokens": 500,
        "totalTokens": 2000,
        "durationMs": 2500,
        "success": true,
        "streamingEnabled": false,
        "toolUseCount": 2,
        "callType": "start"
      }
    ]
  }'

Example Response

{
  "ingested": 1
}

Agent Analytics

The Agent Analytics endpoints provide telemetry-based metrics for agent runs. All analytics endpoints use POST with a JSON body for query parameters.

Base path: /agents/analytics (relative to /api/v1)

Common Query Parameters

Most analytics endpoints accept a common query body based on WorkflowAnalyticsTimeSeriesQuery:

AnalyticsFilter Structure

Analytics Summary

Returns overall metrics including total runs, token usage, success rates, and run duration statistics.

Endpoint: /agents/analytics/summary

Method: POST

Requirements: User must have workflow:run permission.

Headers

Example Request

{
  "from": 1710806400000,
  "to": 1711411200000,
  "filter": {
    "agents": ["<INTERACTION_ID>"]
  }
}

Example Response

{
  "summary": {
    "totalRuns": 142,
    "successfulRuns": 128,
    "failedRuns": 10,
    "ongoingRuns": 4,
    "successRate": 0.927,
    "avgRunDurationMs": 45200,
    "p95RunDurationMs": 120000,
    "nonInteractiveRunCount": 98,
    "tokenUsage": {
      "totalTokens": 2450000,
      "inputTokens": 1800000,
      "outputTokens": 650000
    },
    "nestedInteractionTokens": {
      "totalTokens": 350000,
      "inputTokens": 280000,
      "outputTokens": 70000
    },
    "timeRange": {
      "from": "2025-03-19T00:00:00Z",
      "to": "2025-03-26T00:00:00Z"
    }
  }
}

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/analytics/summary' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": 1710806400000,
    "filter": { "agents": ["<INTERACTION_ID>"] }
  }'

Token Usage Analytics

Returns token consumption metrics. Supports groupBy: model, agent, environment.

Endpoint: /agents/analytics/tokens

Method: POST

Requirements: User must have workflow:run permission.

Example Request

{
  "from": 1710806400000,
  "resolution": "day",
  "groupBy": "model"
}

Example Response

{
  "summary": {
    "totalTokens": 2450000,
    "inputTokens": 1800000,
    "outputTokens": 650000,
    "avgTokensPerCall": 3200
  },
  "timeSeries": [
    {
      "timestamp": "2025-03-19T00:00:00Z",
      "timestampEnd": "2025-03-20T00:00:00Z",
      "usage": { "inputTokens": 280000, "outputTokens": 95000, "totalTokens": 375000 },
      "callCount": 120
    }
  ],
  "byDimension": [
    {
      "dimension": "claude-sonnet-4-6",
      "usage": { "inputTokens": 1200000, "outputTokens": 400000, "totalTokens": 1600000, "avgTokensPerCall": 3500 },
      "callCount": 460,
      "percentageOfTotal": 65.3
    }
  ]
}

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/analytics/tokens' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": 1710806400000,
    "resolution": "hour",
    "groupBy": "model"
  }'

LLM Latency Analytics

Returns duration/latency metrics for LLM calls. Supports groupBy: model.

Endpoint: /agents/analytics/latency/llm

Method: POST

Requirements: User must have workflow:run permission.

Example Response

{
  "summary": {
    "avgMs": 2450,
    "minMs": 800,
    "maxMs": 12000,
    "medianMs": 2100,
    "p95Ms": 6500,
    "p99Ms": 9800,
    "count": 1250,
    "successRate": 0.98
  },
  "byDimension": [
    {
      "dimension": "claude-sonnet-4-6",
      "duration": { "avgMs": 2200, "minMs": 800, "maxMs": 8500, "medianMs": 1900, "p95Ms": 5500, "p99Ms": 7200 },
      "count": 890,
      "successRate": 0.99
    }
  ]
}

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/analytics/latency/llm' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": 1710806400000,
    "groupBy": "model"
  }'

Tool Latency Analytics

Returns duration/latency metrics for tool calls. Supports groupBy: tool.

Endpoint: /agents/analytics/latency/tools

Method: POST

Requirements: User must have workflow:run permission.

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/analytics/latency/tools' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": 1710806400000,
    "groupBy": "tool"
  }'

Agent Run Latency Analytics

Returns duration metrics for complete agent runs.

Endpoint: /agents/analytics/latency/agents

Method: POST

Requirements: User must have workflow:run permission.

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/analytics/latency/agents' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": 1710806400000
  }'

Error Analytics

Returns error rates, error types, and trends. Supports groupBy: model, tool.

Endpoint: /agents/analytics/errors

Method: POST

Requirements: User must have workflow:run permission.

Example Response

{
  "summary": {
    "totalCount": 5000,
    "successCount": 4750,
    "errorCount": 250,
    "errorRate": 0.05,
    "llmErrorCount": 80,
    "toolErrorCount": 170
  },
  "timeSeries": [
    {
      "timestamp": "2025-03-19T00:00:00Z",
      "timestampEnd": "2025-03-19T01:00:00Z",
      "metrics": { "errorRate": 0.03, "errorCount": 5, "llmErrorCount": 2, "toolErrorCount": 3 }
    }
  ],
  "byErrorType": [
    { "errorType": "timeout", "count": 120, "percentageOfErrors": 48.0, "exampleMessage": "Request timed out after 30s" },
    { "errorType": "rate_limit", "count": 80, "percentageOfErrors": 32.0, "exampleMessage": "Rate limit exceeded" }
  ]
}

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/analytics/errors' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": 1710806400000,
    "resolution": "hour",
    "groupBy": "tool"
  }'

Tool Usage Analytics

Returns tool invocation counts, success rates, and performance metrics.

Endpoint: /agents/analytics/tools

Method: POST

Requirements: User must have workflow:run permission.

Example Response

{
  "totalInvocations": 3500,
  "tools": [
    {
      "toolName": "search_documents",
      "toolType": "builtin",
      "invocationCount": 1200,
      "successRate": 0.97,
      "duration": { "avgMs": 150, "minMs": 20, "maxMs": 2000, "p95Ms": 450 },
      "avgInputSizeBytes": 256,
      "avgOutputSizeBytes": 4096
    }
  ]
}

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/analytics/tools' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": 1710806400000
  }'

Tool Parameter Analytics

Returns parameter value distributions for a specific tool.

Endpoint: /agents/analytics/tools/parameters

Method: POST

Requirements: User must have workflow:run permission.

Input Parameters

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/analytics/tools/parameters' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "toolName": "search_documents",
    "from": 1710806400000,
    "limit": 10
  }'

Filter Options

Returns available filter values (agents, environments, models, principals) for populating filter UIs.

Endpoint: /agents/analytics/filter-options

Method: POST

Requirements: User must have workflow:run permission.

Example Response

{
  "agents": [
    { "id": "6801a3f2e4b0d1234abcdef0", "name": "General Agent" }
  ],
  "environmentModels": [
    { "environmentId": "env123", "environmentName": "Production", "modelId": "model456", "modelName": "Claude Sonnet 4.6" }
  ],
  "principals": [
    { "id": "user789", "type": "user", "name": "Jane Doe" },
    { "id": "key012", "type": "apikey", "name": "CI Pipeline Key" }
  ]
}

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/analytics/filter-options' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": 1708214400000
  }'

Prompt Size Analytics

Returns average initial prompt size (input tokens for the first LLM call) per agent, including tools definition overhead.

Endpoint: /agents/analytics/prompt-size

Method: POST

Requirements: User must have workflow:run permission.

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/analytics/prompt-size' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": 1710806400000
  }'

Top Principals

Returns the most active users and API keys by agent run count.

Endpoint: /agents/analytics/top-principals

Method: POST

Requirements: User must have workflow:run permission.

Input Parameters

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/analytics/top-principals' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": 1710806400000,
    "limit": 10
  }'

Runs by Agent

Returns agent run distribution — how many runs per agent/interaction.

Endpoint: /agents/analytics/runs-by-agent

Method: POST

Requirements: User must have workflow:run permission.

Input Parameters

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/analytics/runs-by-agent' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": 1710806400000,
    "limit": 10
  }'

Time to First Response

Measures the time from agent start to completion of the first LLM call. Returns avg, min, max, median, p95, and p99 metrics.

Endpoint: /agents/analytics/time-to-first-response

Method: POST

Requirements: User must have workflow:run permission.

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/analytics/time-to-first-response' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": 1710806400000
  }'

First Response Behavior

Analyzes the agent's first LLM response behavior — percentage that start by creating a plan vs. taking immediate action.

Endpoint: /agents/analytics/first-response-behavior

Method: POST

Requirements: User must have workflow:run permission.

Code Examples

curl -X POST 'https://api.vertesia.io/api/v1/agents/analytics/first-response-behavior' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": 1710806400000
  }'