Obtener Métricas por Organización

Recupera métricas de uso y datos de consumo para toda tu organización.

Endpoints

Obtener Resumen de la Organización

Obtiene el consumo total de créditos de tu organización.

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

Obtener Consumo por Agente

Obtiene el consumo de créditos desglosado por cada agente de tu organización.

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

Autenticación

Estos endpoints requieren autenticación con API key. Incluye tu API key en el encabezado Authorization usando el esquema Bearer.

Formato del Encabezado:

Authorization: Bearer {PUBLIC_KEY}:{SECRET_KEY}

Solicitud

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
organizationId	string (UUID)	Sí	El identificador único de tu organización

Encabezados

Encabezado	Tipo	Requerido	Descripción
Authorization	string	Sí	Tu API key en el formato Bearer pk_xxx:sk_xxx

Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
from	string (ISO 8601)	No	Fecha de inicio para el período de métricas
to	string (ISO 8601)	No	Fecha de fin para el período de métricas

Respuesta

Respuesta del Resumen de la Organización

Código de Estado: 200 OK

Cuerpo de la Respuesta:

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

Campos de la Respuesta (Resumen)

Campo	Tipo	Descripción
data.organization_id	string (UUID)	ID de la organización
data.total_consumption	integer	Total de créditos consumidos durante el período
data.period.from	string | null	Fecha de inicio del período (si se especificó)
data.period.to	string | null	Fecha de fin del período (si se especificó)

Respuesta de Consumo por Agente

Código de Estado: 200 OK

Cuerpo de la Respuesta:

{
  "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
    }
  ]
}

Campos de la Respuesta (Por Agente)

Campo	Tipo	Descripción
data	array	Arreglo de objetos de consumo por agente
data[].agent_id	string (UUID)	Identificador único del agente
data[].name	string	Nombre del agente
data[].total_credits	integer	Total de créditos consumidos por este agente

Respuestas de Error

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"
}

Ejemplos de Uso

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`);
      });
  });

Casos de Uso

Reportes de Facturación Mensual

Genera reportes de consumo mensual para fines de facturación:

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

Análisis de Rendimiento de Agentes

Identifica cuáles agentes se usan más:

// Sort agents by consumption to find top performers

Monitoreo de Presupuesto

Rastrea el consumo de toda la organización contra el presupuesto:

# Alert if consumption exceeds budget threshold

Notas

• Si no se especifica un rango de fechas, se devuelve el consumo de todo el historial
• Los parámetros de fecha deben estar en formato ISO 8601 con zona horaria (por ejemplo, 2024-01-01T00:00:00Z)
• El consumo se mide en créditos (típicamente 3-5 créditos por mensaje dependiendo del modelo)
• El desglose por agente incluye todos los agentes que han procesado al menos un mensaje
• Los agentes eliminados pueden seguir apareciendo en los datos de consumo históricos
• Los resultados no están paginados ya que representan datos de resumen agregados

Endpoints Relacionados

• Obtener Métricas por Agente - Obtener métricas detalladas de un agente específico
• Obtener Métricas por Identificador - Obtener métricas de consumo de un usuario específico
• Obtener Todos los Agentes - Listar todos los agentes de tu organización