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

# Public API

> Read-only HTTP API for accessing AgentOps trace and span data

# Public API

The AgentOps Public API provides read-only HTTP access to your monitoring data. This RESTful API allows you to retrieve trace information, span details, and metrics from any application or framework, regardless of programming language.

<Note>
  This is a **read-only API** for accessing existing data. To create traces and spans, use the [AgentOps SDK](/v2/quickstart) or our instrumentation libraries.
</Note>

## Base URL

All API requests should be made to:

```
https://api.agentops.ai
```

## Authentication

The API uses JWT token authentication. You'll need to exchange your API key for a JWT token first.

### Get Access Token

Convert your API key to a bearer token for API access.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.agentops.ai/public/v1/auth/access_token \
    -H "Content-Type: application/json" \
    -d '{
      "api_key": "YOUR_API_KEY"
    }'
  ```

  ```json Response theme={null}
  {
    "bearer": "eyJhbGciOiJIUzI1NiIs..."
  }
  ```

  ```json Error Response theme={null}
  {
    "detail": [
      {
        "loc": ["body", "api_key"],
        "msg": "field required",
        "type": "value_error.missing"
      }
    ]
  }
  ```
</CodeGroup>

**Important**: Bearer tokens are valid for **30 days**. Store them securely and refresh before expiration.

## Core Endpoints

### Get Project Information

Retrieve details about your current project.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET https://api.agentops.ai/public/v1/project \
    -H "Authorization: Bearer YOUR_BEARER_TOKEN"
  ```

  ```json Response theme={null}
  {
    "id": "proj_abc123",
    "name": "My AI Project",
    "environment": "production"
  }
  ```
</CodeGroup>

This endpoint returns information about the project associated with your API key.

### Get Trace Details

Retrieve comprehensive information about a specific trace, including all its spans.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET https://api.agentops.ai/public/v1/traces/trace_123 \
    -H "Authorization: Bearer YOUR_BEARER_TOKEN"
  ```

  ```json Response theme={null}
  {
    "trace_id": "trace_123",
    "project_id": "proj_abc123",
    "tags": ["production", "chatbot", "gpt-4"],
    "spans": [
      {
        "span_id": "span_456",
        "parent_span_id": null,
        "span_name": "User Query Processing",
        "span_kind": "SPAN_KIND_INTERNAL",
        "start_time": "2024-03-14T12:00:00.000Z",
        "end_time": "2024-03-14T12:00:05.000Z",
        "duration": 5000,
        "status_code": "STATUS_CODE_OK",
        "status_message": "Success"
      },
      {
        "span_id": "span_789",
        "parent_span_id": "span_456",
        "span_name": "OpenAI GPT-4 Call",
        "span_kind": "SPAN_KIND_CLIENT",
        "start_time": "2024-03-14T12:00:01.000Z",
        "end_time": "2024-03-14T12:00:03.000Z",
        "duration": 2000,
        "status_code": "STATUS_CODE_OK",
        "status_message": "Success"
      }
    ]
  }
  ```

  ```json Error Response theme={null}
  {
    "detail": [
      {
        "loc": ["path", "trace_id"],
        "msg": "trace not found",
        "type": "value_error.not_found"
      }
    ]
  }
  ```
</CodeGroup>

**Parameters:**

* `trace_id` (path, required): The unique identifier of the trace

**Response Fields:**

* `trace_id`: Unique trace identifier
* `project_id`: Associated project ID
* `tags`: Array of tags associated with the trace
* `spans`: Array of span summaries within the trace

### Get Trace Metrics

Retrieve aggregated metrics and statistics for a trace.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET https://api.agentops.ai/public/v1/traces/trace_123/metrics \
    -H "Authorization: Bearer YOUR_BEARER_TOKEN"
  ```

  ```json Response theme={null}
  {
    "span_count": 5,
    "trace_count": 1,
    "success_count": 4,
    "fail_count": 1,
    "indeterminate_count": 0,
    "prompt_tokens": 150,
    "completion_tokens": 75,
    "cache_read_input_tokens": 0,
    "reasoning_tokens": 25,
    "total_tokens": 250,
    "prompt_cost": "0.0030",
    "completion_cost": "0.0015",
    "average_cost_per_trace": "0.0045",
    "total_cost": "0.0045"
  }
  ```
</CodeGroup>

**Metrics Explained:**

* `span_count`: Total number of spans in the trace
* `success_count`/`fail_count`/`indeterminate_count`: Status breakdown
* `*_tokens`: Token usage breakdown by type
* `*_cost`: Cost calculations in USD

### Get Span Details

Retrieve comprehensive information about a specific span, including full attribute payloads.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET https://api.agentops.ai/public/v1/spans/span_456 \
    -H "Authorization: Bearer YOUR_BEARER_TOKEN"
  ```

  ```json Response theme={null}
  {
    "span_id": "span_456",
    "parent_span_id": null,
    "span_name": "User Query Processing",
    "span_kind": "SPAN_KIND_INTERNAL",
    "service_name": "chatbot-service",
    "start_time": "2024-03-14T12:00:00.000Z",
    "end_time": "2024-03-14T12:00:05.000Z",
    "duration": 5000,
    "status_code": "STATUS_CODE_OK",
    "status_message": "Success",
    "attributes": {
      "llm.model": "gpt-4-turbo",
      "llm.prompt": "What is the weather like today?",
      "llm.completion": "I need your location to provide weather information.",
      "llm.usage.prompt_tokens": 50,
      "llm.usage.completion_tokens": 25
    },
    "resource_attributes": {
      "service.name": "chatbot-service",
      "service.version": "1.2.3"
    },
    "span_attributes": {
      "user_id": "user_123",
      "session_id": "session_456"
    }
  }
  ```
</CodeGroup>

**Parameters:**

* `span_id` (path, required): The unique identifier of the span

**Response Fields:**

* `attributes`: Core span data (LLM calls, tool usage, etc.)
* `resource_attributes`: Service and infrastructure metadata
* `span_attributes`: Custom attributes set by your application

### Get Span Metrics

Retrieve detailed metrics for a specific span.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET https://api.agentops.ai/public/v1/spans/span_456/metrics \
    -H "Authorization: Bearer YOUR_BEARER_TOKEN"
  ```

  ```json Response theme={null}
  {
    "total_tokens": 75,
    "prompt_tokens": 50,
    "completion_tokens": 25,
    "cache_read_input_tokens": 0,
    "reasoning_tokens": 0,
    "success_tokens": 75,
    "fail_tokens": 0,
    "indeterminate_tokens": 0,
    "prompt_cost": "0.0015",
    "completion_cost": "0.0005",
    "total_cost": "0.0020"
  }
  ```
</CodeGroup>

## MCP Server

AgentOps provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes the Public API as tools for AI assistants. This allows AI models to directly query your AgentOps data during conversations.

### Configuration

Create an MCP server configuration file (typically `mcp_config.json`):

**Python-based configuration:**

```json theme={null}
{
  "mcpServers": {
    "agentops": {
      "command": "python",
      "args": ["-m", "agentops.mcp.server"],
      "env": {
        "AGENTOPS_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**Docker-based configuration:**

```json theme={null}
{
  "mcpServers": {
    "agentops": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "AGENTOPS_API_KEY",
        "agentops/agentops-mcp:latest"
      ],
      "env": {
        "AGENTOPS_API_KEY": "your-agentops-api-key-here"
      }
    }
  }
}
```

### Available Tools

The MCP server exposes the following tools that mirror the Public API endpoints:

#### `auth`

Authorize using an AgentOps project API key.

* **Parameters**: `api_key` (string) - Your AgentOps project API key
* **Usage**: The server will automatically prompt for authentication when needed

#### `get_project`

Get details about the current project.

* **Parameters**: None
* **Returns**: Project information including ID, name, and environment

#### `get_trace`

Get comprehensive trace information by ID.

* **Parameters**: `trace_id` (string) - The trace identifier
* **Returns**: Trace details with associated spans

#### `get_trace_metrics`

Get aggregated metrics for a specific trace.

* **Parameters**: `trace_id` (string) - The trace identifier
* **Returns**: Cost, token usage, and performance metrics

#### `get_span`

Get detailed span information by ID.

* **Parameters**: `span_id` (string) - The span identifier
* **Returns**: Complete span data including attributes

#### `get_span_metrics`

Get metrics for a specific span.

* **Parameters**: `span_id` (string) - The span identifier
* **Returns**: Span-specific cost and token metrics

### Environment Variables

The MCP server supports the following environment variables:

* `AGENTOPS_API_KEY`: Your AgentOps project API key
* `HOST`: API endpoint (defaults to `https://api.agentops.ai`)