> ## Documentation Index
> Fetch the complete documentation index at: https://moonshotfactory.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.agentvista.dev/api/v1/agents \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`GET /agents`

Returns all agents for the authenticated user with aggregated summary statistics.

### Response — 200

An array of agent summary objects.

<ResponseField name="id" type="string">
  Agent UUID.
</ResponseField>

<ResponseField name="name" type="string">
  Agent name as provided during ingestion.
</ResponseField>

<ResponseField name="total_runs" type="number">
  Total number of traces (runs) for this agent.
</ResponseField>

<ResponseField name="success_rate" type="number | null">
  Percentage of runs with `success: true` (e.g. `73.2` = 73.2%). Null if no runs have a success signal.
</ResponseField>

<ResponseField name="total_cost" type="number | null">
  Total LLM cost in USD across all runs.
</ResponseField>

<ResponseField name="avg_cost_per_run" type="number | null">
  Average `total_cost_usd` per run in USD.
</ResponseField>

<ResponseField name="last_run_at" type="string | null">
  ISO 8601 timestamp of the most recent trace.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when this agent record was first created.
</ResponseField>

```json Example response theme={null}
[
  {
    "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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.agentvista.dev/api/v1/agents/3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`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

<ParamField path="agent_id" type="string" required>
  UUID of the agent.
</ParamField>

### Response — 200

All fields from the [list response](#list-agents), plus:

<ResponseField name="successful_runs" type="number">
  Number of runs with `success: true`.
</ResponseField>

<ResponseField name="failed_runs" type="number">
  Number of runs with `success: false`.
</ResponseField>

```json Example response theme={null}
{
  "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

<CodeGroup>
  ```bash 7-day stats theme={null}
  curl "https://api.agentvista.dev/api/v1/agents/3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a/stats?days=7" \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```bash 30-day stats theme={null}
  curl "https://api.agentvista.dev/api/v1/agents/3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a/stats?days=30" \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`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

<ParamField path="agent_id" type="string" required>
  UUID of the agent.
</ParamField>

### Query parameters

<ParamField query="days" type="number" default="7">
  Number of days to include. Accepted values: `7`, `30`, `90`. Any other value is treated as `7`.
</ParamField>

### Response — 200

<ResponseField name="agent_id" type="string">
  Agent UUID.
</ResponseField>

<ResponseField name="agent_name" type="string">
  Agent name.
</ResponseField>

<ResponseField name="date_range" type="string">
  The requested window as a string: `"7d"`, `"30d"`, or `"90d"`.
</ResponseField>

<ResponseField name="daily" type="object[]">
  One entry per day in the date range.

  <Expandable title="daily stat fields">
    <ResponseField name="date" type="string">
      Date in `YYYY-MM-DD` format.
    </ResponseField>

    <ResponseField name="total_runs" type="number">
      Number of traces started on this date.
    </ResponseField>

    <ResponseField name="successful_runs" type="number">
      Number of traces with `success: true` on this date.
    </ResponseField>

    <ResponseField name="success_rate" type="number | null">
      Success rate as a percentage for this date.
    </ResponseField>

    <ResponseField name="total_cost" type="number | null">
      Total LLM cost in USD for this date.
    </ResponseField>
  </Expandable>
</ResponseField>

```json Example response theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.agentvista.dev/api/v1/agents/3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a/runs?page=1&page_size=20" \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`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

<ParamField path="agent_id" type="string" required>
  UUID of the agent.
</ParamField>

### Query parameters

<ParamField query="page" type="number" default="1">
  Page number (1-indexed).
</ParamField>

<ParamField query="page_size" type="number" default="20">
  Number of traces per page. Clamped to `1–100`.
</ParamField>

### Response — 200

<ResponseField name="traces" type="object[]">
  Array of trace summaries for the current page.

  <Expandable title="trace fields">
    <ResponseField name="id" type="string">Internal UUID (primary key).</ResponseField>
    <ResponseField name="trace_id" type="string">SDK-provided trace UUID.</ResponseField>
    <ResponseField name="started_at" type="string">ISO 8601 start timestamp.</ResponseField>
    <ResponseField name="duration_ms" type="number | null">Duration in milliseconds.</ResponseField>
    <ResponseField name="status" type="string">Trace status: `running`, `completed`, `failed`, or `timed_out`.</ResponseField>
    <ResponseField name="success" type="boolean | null">Outcome signal, or null if not set.</ResponseField>
    <ResponseField name="outcome" type="string | null">Free-text outcome description.</ResponseField>
    <ResponseField name="total_tokens" type="number | null">Total tokens consumed.</ResponseField>
    <ResponseField name="total_cost_usd" type="number | null">Total LLM cost in USD.</ResponseField>
    <ResponseField name="error_message" type="string | null">Error description if the run failed.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number">
  Total number of traces for this agent (before pagination).
</ResponseField>

<ResponseField name="page" type="number">
  Current page number.
</ResponseField>

<ResponseField name="page_size" type="number">
  Number of traces per page.
</ResponseField>

<ResponseField name="has_next" type="boolean">
  Whether there are more pages after this one.
</ResponseField>