Skip to main content
GET
/
api
/
v1
/
messages
Messages Log
curl --request GET \
  --url https://api.example.com/api/v1/messages
{
  "items": [
    {
      "id": "<string>",
      "timestamp": "<string>",
      "agent_name": "<string>",
      "model": {},
      "description": {},
      "service_type": {},
      "input_tokens": 123,
      "output_tokens": 123,
      "cache_read_tokens": 123,
      "cache_creation_tokens": 123,
      "total_tokens": 123,
      "cost": {},
      "status": "<string>",
      "error_message": {},
      "duration_ms": {},
      "routing_tier": {},
      "routing_reason": {}
    }
  ],
  "next_cursor": {},
  "total_count": 123,
  "models": [
    {}
  ]
}

​
Overview

The messages endpoint provides a paginated list of individual agent messages with detailed metadata. It supports cursor-based pagination for efficient data fetching and offers advanced filtering by status, service type, model, and cost range. Messages are the core telemetry unit in Manifest — each message represents a single LLM interaction or agent action.

​
Authentication

Requires session authentication (cookie) or API key via X-API-Key header.

​
Query Parameters

​
range
string
Time range filter. Valid values: 1h, 6h, 24h, 7d, 30dIf omitted, returns messages across all time.
​
agent_name
string
Filter to a specific agent
​
status
string
Filter by message status. Common values: ok, error
​
service_type
string
Filter by service type (e.g., llm, tool, embedding)
​
model
string
Filter by LLM model (e.g., claude-4.5-sonnet, gpt-4o)
​
cost_min
number
Minimum cost in USD (inclusive). Must be greater than or equal to 0.
​
cost_max
number
Maximum cost in USD (inclusive). Must be less than or equal to 999999.
​
limit
number
default:"50"
Number of messages to return per page. Min: 1, Max: 200.
​
cursor
string
Pagination cursor from previous response’s next_cursor field.Format: <timestamp>|<id> (internal, treated as opaque by clients)

​
Response Schema

​
items
array
Array of message objects, ordered by timestamp descending (newest first)
​
next_cursor
string | null
Cursor for fetching the next page. null if no more results.Pass this value as the cursor query parameter to fetch the next page.
​
total_count
number
Total number of messages matching the filters (across all pages)
​
models
array
Distinct list of models present in the filtered dataset, ordered alphabetically.Useful for populating filter dropdowns in the UI.

​
Pagination

This endpoint uses cursor-based pagination for efficiency:
  1. Initial request: Omit cursor parameter
  2. Response includes next_cursor if more results exist
  3. Subsequent requests: Pass next_cursor as cursor parameter
  4. Stop when next_cursor is null
Example pagination flow
# Page 1
curl "https://api.manifest.build/api/v1/messages?limit=50"
# Returns: { "items": [...], "next_cursor": "2026-03-04T10:30:00Z|msg_123", ... }

# Page 2
curl "https://api.manifest.build/api/v1/messages?limit=50&cursor=2026-03-04T10:30:00Z|msg_123"
# Returns: { "items": [...], "next_cursor": "2026-03-04T08:15:00Z|msg_456", ... }

# Page 3
curl "https://api.manifest.build/api/v1/messages?limit=50&cursor=2026-03-04T08:15:00Z|msg_456"
# Returns: { "items": [...], "next_cursor": null, ... }

​
Example Request

cURL
curl -X GET "https://api.manifest.build/api/v1/messages?range=24h&status=ok&model=claude-4.5-sonnet&limit=20" \
  -H "X-API-Key: your-api-key"

​
Example Response

{
  "items": [
    {
      "id": "msg_abc123xyz",
      "timestamp": "2026-03-04T10:30:15Z",
      "agent_name": "customer-support-agent",
      "model": "claude-4.5-sonnet",
      "description": "Customer inquiry response",
      "service_type": "llm",
      "input_tokens": 2500,
      "output_tokens": 1200,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "total_tokens": 3700,
      "cost": 0.015,
      "status": "ok",
      "error_message": null,
      "duration_ms": 2340,
      "routing_tier": "smart",
      "routing_reason": "complex_query"
    },
    {
      "id": "msg_def456uvw",
      "timestamp": "2026-03-04T10:28:42Z",
      "agent_name": "customer-support-agent",
      "model": "claude-4.5-sonnet",
      "description": "Knowledge base search",
      "service_type": "tool",
      "input_tokens": 150,
      "output_tokens": 80,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "total_tokens": 230,
      "cost": 0.001,
      "status": "ok",
      "error_message": null,
      "duration_ms": 450,
      "routing_tier": null,
      "routing_reason": null
    }
  ],
  "next_cursor": "2026-03-04T10:28:42Z|msg_def456uvw",
  "total_count": 127,
  "models": [
    "claude-4.5-sonnet",
    "gpt-4o",
    "gemini-2.0-flash"
  ]
}

​
Filtering Tips

​
Cost-based filtering

Find expensive messages: 
curl "https://api.manifest.build/api/v1/messages?cost_min=0.10&limit=50"

​
Error tracking

Monitor failures: 
curl "https://api.manifest.build/api/v1/messages?status=error&range=24h"

​
Model comparison

Analyze specific model usage: 
curl "https://api.manifest.build/api/v1/messages?model=gpt-4o&range=7d"

​
Combined filters

Complex queries: 
curl "https://api.manifest.build/api/v1/messages?service_type=llm&cost_min=0.05&cost_max=0.50&status=ok&range=30d&limit=100"

​
Notes

  • Sorting: Messages are always ordered by timestamp DESC, id DESC for consistent pagination.
  • Cost sanitization: Negative costs (invalid pricing) are returned as null in the response.
  • Cache tokens: Prompt caching tokens (cache_read_tokens, cache_creation_tokens) are tracked separately and not included in total_tokens.
  • Multi-tenancy: Data is automatically filtered by authenticated user.
  • Performance: Cursor-based pagination is more efficient than offset-based for large datasets.
  • Model list: The models array is computed across the entire filtered dataset (not just the current page), making it useful for building filter UIs.
  • No caching: Unlike other analytics endpoints, messages are not cached to ensure real-time data.

Build docs developers (and LLMs) love

Get started for freeTalk to us