Skip to main content
Agents are auto-created when you ingest the first trace for a new agent name. All agent endpoints are read-only — agents are managed through trace ingestion. All queries are scoped to the authenticated user. Agents belonging to other users are never returned.

​
List agents

curl https://api.agentvista.dev/api/v1/agents \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
GET /agents Returns all agents for the authenticated user with aggregated summary statistics.

​
Response — 200

An array of agent summary objects.
​
id
string
Agent UUID.
​
name
string
Agent name as provided during ingestion.
​
total_runs
number
Total number of traces (runs) for this agent.
​
success_rate
number | null
Percentage of runs with success: true (e.g. 73.2 = 73.2%). Null if no runs have a success signal.
​
total_cost
number | null
Total LLM cost in USD across all runs.
​
avg_cost_per_run
number | null
Average total_cost_usd per run in USD.
​
last_run_at
string | null
ISO 8601 timestamp of the most recent trace.
​
created_at
string
ISO 8601 timestamp when this agent record was first created.
Example response
[
  {
    "id": "3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a",
    "name": "lead-qualifier",
    "total_runs": 1842,
    "success_rate": 73.2,
    "total_cost": 184.21,
    "avg_cost_per_run": 0.10,
    "last_run_at": "2024-01-15T12:05:00Z",
    "created_at": "2023-11-01T08:00:00Z"
  }
]

​
Get agent detail

curl https://api.agentvista.dev/api/v1/agents/3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
GET /agents/{agent_id} Returns full detail for a single agent, extending the summary fields with per-outcome run counts. Returns 404 if the agent does not exist or does not belong to the authenticated user.

​
Path parameters

​
agent_id
string
required
UUID of the agent.

​
Response — 200

All fields from the list response, plus:
​
successful_runs
number
Number of runs with success: true.
​
failed_runs
number
Number of runs with success: false.
Example response
{
  "id": "3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a",
  "name": "lead-qualifier",
  "total_runs": 1842,
  "success_rate": 73.2,
  "total_cost": 184.21,
  "avg_cost_per_run": 0.10,
  "last_run_at": "2024-01-15T12:05:00Z",
  "created_at": "2023-11-01T08:00:00Z",
  "successful_runs": 1348,
  "failed_runs": 494
}

​
Get agent time-series stats

curl "https://api.agentvista.dev/api/v1/agents/3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a/stats?days=7" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
GET /agents/{agent_id}/stats Returns daily aggregated statistics for an agent over a rolling time window. Returns 404 if the agent is not found.

​
Path parameters

​
agent_id
string
required
UUID of the agent.

​
Query parameters

​
days
number
default:"7"
Number of days to include. Accepted values: 7, 30, 90. Any other value is treated as 7.

​
Response — 200

​
agent_id
string
Agent UUID.
​
agent_name
string
Agent name.
​
date_range
string
The requested window as a string: "7d", "30d", or "90d".
​
daily
object[]
One entry per day in the date range.
Example response
{
  "agent_id": "3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a",
  "agent_name": "lead-qualifier",
  "date_range": "7d",
  "daily": [
    {
      "date": "2024-01-15",
      "total_runs": 312,
      "successful_runs": 228,
      "success_rate": 73.1,
      "total_cost": 31.2
    },
    {
      "date": "2024-01-14",
      "total_runs": 287,
      "successful_runs": 210,
      "success_rate": 73.2,
      "total_cost": 28.7
    }
  ]
}

​
Get agent run history

curl "https://api.agentvista.dev/api/v1/agents/3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a/runs?page=1&page_size=20" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
GET /agents/{agent_id}/runs Returns paginated trace history for an agent, ordered newest-first. Returns 404 if the agent is not found.

​
Path parameters

​
agent_id
string
required
UUID of the agent.

​
Query parameters

​
page
number
default:"1"
Page number (1-indexed).
​
page_size
number
default:"20"
Number of traces per page. Clamped to 1–100.

​
Response — 200

​
traces
object[]
Array of trace summaries for the current page.
​
total
number
Total number of traces for this agent (before pagination).
​
page
number
Current page number.
​
page_size
number
Number of traces per page.
​
has_next
boolean
Whether there are more pages after this one.