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

# Agent Statistics

> Retrieve usage statistics for a specific agent

Retrieve usage statistics for a specific agent.

### Endpoint

```bash
GET /agent/{agent_id}/stats
```

### Parameters

<ParamField path="agent_id" type="string" required>
  ID of the agent to get statistics for
</ParamField>

### Response

<ResponseField name="message_distribution" type="object" required>
  <Expandable title="Properties">
    <ResponseField name="sample_size" type="integer">Number of messages in the sample</ResponseField>
    <ResponseField name="assistant_messages" type="integer">Number of assistant messages</ResponseField>
    <ResponseField name="user_messages" type="integer">Number of user messages</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="response_time" type="object" required>
  <Expandable title="Properties">
    <ResponseField name="sample_size" type="integer">Number of responses in the sample</ResponseField>
    <ResponseField name="min_seconds" type="number">Minimum response time in seconds</ResponseField>
    <ResponseField name="average_seconds" type="number">Average response time in seconds</ResponseField>
    <ResponseField name="max_seconds" type="number">Maximum response time in seconds</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="agent_id" type="string" required>
  ID of the agent
</ResponseField>

<ResponseField name="total_conversations" type="integer">
  Total number of conversations
</ResponseField>

<ResponseField name="total_messages" type="integer">
  Total number of messages
</ResponseField>

<ResponseField name="stats_generated_at" type="string">
  Timestamp when these statistics were generated
</ResponseField>

```json
{
  "message_distribution": {
    "sample_size": 5,
    "assistant_messages": 5,
    "user_messages": 5
  },
  "response_time": {
    "sample_size": 5,
    "min_seconds": 3.77,
    "average_seconds": 17.41,
    "max_seconds": 24.99
  },
  "agent_id": "2ec10f28abac4e01",
  "total_conversations": 610,
  "total_messages": 100,
  "stats_generated_at": "2025-02-23T21:01:00.750638+00:00"
}
```


## OpenAPI

````yaml GET /agent/{agent_id}/stats
openapi: 3.0.0
info:
  title: Headless Agents API
  description: >-
    The Headless Agents API allows you to interact with AI agents
    programmatically. 

    This API provides endpoints for health checking, calling agents, and
    retrieving agent statistics.


    ## Authentication

    All API requests (except /health) require authentication using your Headless
    Agents API key provided as an `X-API-Key` header.


    Example:

    ```bash

    curl -H "X-API-Key: your_api_key"
    https://api.headlessagents.ai/call/your_agent_id

    ```
  version: 1.0.0
  contact:
    name: Headless Agents Support
    url: https://headlessagents.ai
    email: support@headlessagents.ai
servers:
  - url: https://api.headlessagents.ai
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Health
    description: Health check endpoints
  - name: Agents
    description: Endpoints for interacting with agents
paths:
  /agent/{agent_id}/stats:
    get:
      tags:
        - Agents
      summary: Get agent statistics
      description: Retrieve usage statistics for a specific agent
      operationId: getAgentStats
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
          description: ID of the agent to get statistics for
      responses:
        '200':
          description: Agent statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentStats'
              example:
                message_distribution:
                  sample_size: 5
                  assistant_messages: 5
                  user_messages: 5
                response_time:
                  sample_size: 5
                  min_seconds: 3.77
                  average_seconds: 17.41
                  max_seconds: 24.99
                agent_id: 2ec10f28abac4e01
                turns_per_conversation:
                  sample_size: 5
                  average: 1
                message_length:
                  user:
                    sample_size: 5
                    average: 11
                    min: 11
                    max: 11
                  assistant:
                    sample_size: 5
                    average: 94.4
                    min: 92
                    max: 101
                total_conversations: 610
                messages_per_conversation:
                  average: 2
                  max: 2
                  min: 2
                total_messages: 100
                stats_generated_at: '2025-02-23T21:01:00.750638+00:00'
                usage_timeline:
                  last_7d: 50
                  first_conversation: '2025-02-23T19:48:13.405391+00:00'
                  last_24h: 50
                  last_conversation: '2025-02-23T19:55:13.683286+00:00'
                  last_30d: 50
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AgentStats:
      type: object
      properties:
        message_distribution:
          type: object
          properties:
            sample_size:
              type: integer
            assistant_messages:
              type: integer
            user_messages:
              type: integer
        response_time:
          type: object
          properties:
            sample_size:
              type: integer
            min_seconds:
              type: number
              format: float
            average_seconds:
              type: number
              format: float
            max_seconds:
              type: number
              format: float
        agent_id:
          type: string
        turns_per_conversation:
          type: object
          properties:
            sample_size:
              type: integer
            average:
              type: number
              format: float
        message_length:
          type: object
          properties:
            user:
              type: object
              properties:
                sample_size:
                  type: integer
                average:
                  type: number
                  format: float
                min:
                  type: integer
                max:
                  type: integer
            assistant:
              type: object
              properties:
                sample_size:
                  type: integer
                average:
                  type: number
                  format: float
                min:
                  type: integer
                max:
                  type: integer
        total_conversations:
          type: integer
        messages_per_conversation:
          type: object
          properties:
            average:
              type: number
              format: float
            max:
              type: integer
            min:
              type: integer
        total_messages:
          type: integer
        stats_generated_at:
          type: string
          format: date-time
        usage_timeline:
          type: object
          properties:
            last_7d:
              type: integer
            first_conversation:
              type: string
              format: date-time
            last_24h:
              type: integer
            last_conversation:
              type: string
              format: date-time
            last_30d:
              type: integer
      required:
        - agent_id
        - stats_generated_at
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message detailing what went wrong
      required:
        - detail
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key provided by Headless Agents

````