---
title: "Public API"
description: "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
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
{
  "bearer": "eyJhbGciOiJIUzI1NiIs..."
}
```

```json Error Response
{
  "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
curl -X GET https://api.agentops.ai/public/v1/project \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"
```

```json Response
{
  "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
curl -X GET https://api.agentops.ai/public/v1/traces/trace_123 \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"
```

```json Response
{
  "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
{
  "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
curl -X GET https://api.agentops.ai/public/v1/traces/trace_123/metrics \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"
```

```json Response
{
  "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
curl -X GET https://api.agentops.ai/public/v1/spans/span_456 \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"
```

```json Response
{
  "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
curl -X GET https://api.agentops.ai/public/v1/spans/span_456/metrics \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"
```

```json Response
{
  "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
{
  "mcpServers": {
    "agentops": {
      "command": "python",
      "args": ["-m", "agentops.mcp.server"],
      "env": {
        "AGENTOPS_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**Docker-based configuration:**
```json
{
  "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`)