Agents

List agents, view agent detail, and query time-series stats and run history.

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

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

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

7-day 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.

Show daily stat fields

date · string

Date in YYYY-MM-DD format.

total_runs · number

Number of traces started on this date.

successful_runs · number

Number of traces with success: true on this date.

success_rate · number | null

Success rate as a percentage for this date.

total_cost · number | null

Total LLM cost in USD for this date.

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

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.

Show trace fields

id · string

Internal UUID (primary key).

trace_id · string

SDK-provided trace UUID.

started_at · string

ISO 8601 start timestamp.

duration_ms · number | null

Duration in milliseconds.

status · string

Trace status: running, completed, failed, or timed_out.

success · boolean | null

Outcome signal, or null if not set.

outcome · string | null

Free-text outcome description.

total_tokens · number | null

Total tokens consumed.

total_cost_usd · number | null

Total LLM cost in USD.

error_message · string | null

Error description if the run failed.

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.