​

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.

​

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.

curl -X POST https://api.agentops.ai/public/v1/auth/access_token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY"
  }'

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.

curl -X GET https://api.agentops.ai/public/v1/project \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

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.

curl -X GET https://api.agentops.ai/public/v1/traces/trace_123 \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

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.

curl -X GET https://api.agentops.ai/public/v1/traces/trace_123/metrics \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

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.

curl -X GET https://api.agentops.ai/public/v1/spans/span_456 \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

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.

curl -X GET https://api.agentops.ai/public/v1/spans/span_456/metrics \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

​

MCP Server

AgentOps provides a Model Context Protocol (MCP) 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:

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

Docker-based configuration:

{
  "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)