Get Metrics by Organization

Retrieve usage metrics and consumption data for your entire organization.

Endpoints

Get Organization Summary

Get total credit consumption for your organization.

GET /api/v1/consumption/organization/{organizationId}/summary

Get Consumption by Agent

Get credit consumption broken down by each agent in your organization.

GET /api/v1/consumption/organization/{organizationId}/agents

Authentication

These endpoints require API key authentication. Include your API key in the Authorization header using the Bearer scheme.

Header Format:

Authorization: Bearer {PUBLIC_KEY}:{SECRET_KEY}

Request

Path Parameters

Parameter	Type	Required	Description
`organizationId`	string (UUID)	Yes	The unique identifier of your organization

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Your API key in the format `Bearer pk_xxx:sk_xxx`

Query Parameters

Parameter	Type	Required	Description
`from`	string (ISO 8601)	No	Start date for the metrics period
`to`	string (ISO 8601)	No	End date for the metrics period

Response

Organization Summary Response

Status Code: 200 OK

Response Body:

{
  "data": {
    "organization_id": "770e8400-e29b-41d4-a716-446655440000",
    "total_consumption": 15420,
    "period": {
      "from": "2024-01-01T00:00:00Z",
      "to": "2024-01-31T23:59:59Z"
    }
  }
}

Response Fields (Summary)

Field	Type	Description
`data.organization_id`	string (UUID)	ID of the organization
`data.total_consumption`	integer	Total credits consumed during the period
`data.period.from`	string \| null	Start date of the period (if specified)
`data.period.to`	string \| null	End date of the period (if specified)

Consumption by Agent Response

Status Code: 200 OK

Response Body:

{
  "data": [
    {
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Customer Support Agent",
      "total_credits": 8750
    },
    {
      "agent_id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Sales Assistant",
      "total_credits": 4200
    },
    {
      "agent_id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "Technical Support Bot",
      "total_credits": 2470
    }
  ]
}

Response Fields (By Agent)

Field	Type	Description
`data`	array	Array of agent consumption objects
`data[].agent_id`	string (UUID)	Unique identifier of the agent
`data[].name`	string	Name of the agent
`data[].total_credits`	integer	Total credits consumed by this agent

Error Responses

401 Unauthorized

Status: 401 Unauthorized
{
  "error": "Invalid or missing API key"
}

403 Forbidden

Status: 403 Forbidden
{
  "error": "Access denied to this organization"
}

500 Internal Server Error

Status: 500 Internal Server Error
{
  "error": "Internal server error"
}

Example Usage

cURL

# Get organization summary
curl -X GET "https://agentsgt.com/api/v1/consumption/organization/770e8400-e29b-41d4-a716-446655440000/summary" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

# Get summary for specific date range
curl -X GET "https://agentsgt.com/api/v1/consumption/organization/770e8400-e29b-41d4-a716-446655440000/summary?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

# Get consumption by agent
curl -X GET "https://agentsgt.com/api/v1/consumption/organization/770e8400-e29b-41d4-a716-446655440000/agents" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

# Get consumption by agent for date range
curl -X GET "https://agentsgt.com/api/v1/consumption/organization/770e8400-e29b-41d4-a716-446655440000/agents?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

JavaScript (Fetch API)

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';
const organizationId = '770e8400-e29b-41d4-a716-446655440000';

// Get organization summary
fetch(`https://agentsgt.com/api/v1/consumption/organization/${organizationId}/summary`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => {
    console.log(`Total consumption: ${data.data.total_consumption} credits`);
  });

// Get consumption by agent with date filter
const params = new URLSearchParams({
  from: '2024-01-01T00:00:00Z',
  to: '2024-01-31T23:59:59Z'
});

fetch(`https://agentsgt.com/api/v1/consumption/organization/${organizationId}/agents?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => {
    console.log('Consumption by agent:');
    data.data.forEach(agent => {
      console.log(`- ${agent.name}: ${agent.total_credits} credits`);
    });

    // Calculate total
    const total = data.data.reduce((sum, agent) => sum + agent.total_credits, 0);
    console.log(`\nTotal: ${total} credits`);
  });

Python (Requests)

import requests
from datetime import datetime, timedelta

public_key = 'pk_1234567890abcdef'
secret_key = 'sk_abcdef1234567890'
organization_id = '770e8400-e29b-41d4-a716-446655440000'

headers = {
    'Authorization': f'Bearer {public_key}:{secret_key}',
    'Content-Type': 'application/json'
}

# Get organization summary
response = requests.get(
    f'https://agentsgt.com/api/v1/consumption/organization/{organization_id}/summary',
    headers=headers
)

if response.status_code == 200:
    data = response.json()
    print(f"Organization ID: {data['data']['organization_id']}")
    print(f"Total consumption: {data['data']['total_consumption']} credits")
else:
    print(f"Error: {response.status_code} - {response.json()}")

# Get consumption by agent for last 30 days
end_date = datetime.now()
start_date = end_date - timedelta(days=30)

params = {
    'from': start_date.isoformat() + 'Z',
    'to': end_date.isoformat() + 'Z'
}

response = requests.get(
    f'https://agentsgt.com/api/v1/consumption/organization/{organization_id}/agents',
    headers=headers,
    params=params
)

if response.status_code == 200:
    data = response.json()
    print(f"\nConsumption by agent (last 30 days):")

    # Sort by consumption (highest first)
    sorted_agents = sorted(
        data['data'],
        key=lambda x: x['total_credits'],
        reverse=True
    )

    for agent in sorted_agents:
        print(f"  {agent['name']}: {agent['total_credits']} credits")

    # Calculate percentage for each agent
    total = sum(agent['total_credits'] for agent in sorted_agents)
    print(f"\nBreakdown:")
    for agent in sorted_agents:
        percentage = (agent['total_credits'] / total * 100) if total > 0 else 0
        print(f"  {agent['name']}: {percentage:.1f}%")

Node.js (Axios)

const axios = require('axios');

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';
const organizationId = '770e8400-e29b-41d4-a716-446655440000';

const headers = {
  'Authorization': `Bearer ${publicKey}:${secretKey}`,
  'Content-Type': 'application/json'
};

// Function to get organization metrics
async function getOrganizationMetrics(from, to) {
  try {
    // Get summary
    const summaryResponse = await axios.get(
      `https://agentsgt.com/api/v1/consumption/organization/${organizationId}/summary`,
      {
        headers,
        params: { from, to }
      }
    );

    // Get breakdown by agent
    const agentsResponse = await axios.get(
      `https://agentsgt.com/api/v1/consumption/organization/${organizationId}/agents`,
      {
        headers,
        params: { from, to }
      }
    );

    return {
      summary: summaryResponse.data.data,
      agents: agentsResponse.data.data
    };
  } catch (error) {
    console.error('Error fetching metrics:', error.response?.data || error.message);
    throw error;
  }
}

// Get metrics for current month
const now = new Date();
const startOfMonth = new Date(now.getFullYear(), now.getMonth(), 1).toISOString();
const endOfMonth = new Date(now.getFullYear(), now.getMonth() + 1, 0, 23, 59, 59).toISOString();

getOrganizationMetrics(startOfMonth, endOfMonth)
  .then(metrics => {
    console.log('Organization Metrics');
    console.log('===================');
    console.log(`Total Consumption: ${metrics.summary.total_consumption} credits`);
    console.log(`Period: ${metrics.summary.period.from} to ${metrics.summary.period.to}`);

    console.log('\nTop Agents by Consumption:');
    metrics.agents
      .sort((a, b) => b.total_credits - a.total_credits)
      .slice(0, 5)
      .forEach((agent, index) => {
        console.log(`${index + 1}. ${agent.name}: ${agent.total_credits} credits`);
      });
  });

Use Cases

Monthly Billing Reports

Generate monthly consumption reports for billing purposes:

# Get consumption for billing month
params = {'from': '2024-01-01T00:00:00Z', 'to': '2024-01-31T23:59:59Z'}

Agent Performance Analysis

Identify which agents are most heavily used:

// Sort agents by consumption to find top performers

Budget Monitoring

Track organization-wide consumption against budget:

# Alert if consumption exceeds budget threshold

Notes

If no date range is specified, all-time consumption is returned
Date parameters should be in ISO 8601 format with timezone (e.g., 2024-01-01T00:00:00Z)
Consumption is measured in credits (typically 3-5 credits per message depending on model)
The agent breakdown includes all agents that have processed at least one message
Deleted agents may still appear in historical consumption data
Results are not paginated as they represent aggregated summary data

Get Metrics by Agent - Get detailed metrics for a specific agent
Get Metrics by Identifier - Get consumption metrics for a specific user
Get All Agents - List all agents in your organization

Endpoints​

Get Organization Summary​

Get Consumption by Agent​

Authentication​

Request​

Path Parameters​

Headers​

Query Parameters​

Response​

Organization Summary Response​

Response Fields (Summary)​

Consumption by Agent Response​

Response Fields (By Agent)​

Error Responses​

401 Unauthorized​

403 Forbidden​

500 Internal Server Error​

Example Usage​

cURL​

JavaScript (Fetch API)​

Python (Requests)​

Node.js (Axios)​

Use Cases​

Monthly Billing Reports​

Agent Performance Analysis​

Budget Monitoring​

Notes​

Related Endpoints​