Obtener Métricas por Agente

Recupera métricas detalladas de uso y datos de consumo para un agente específico.

Endpoints

Obtener Consumo Diario

Obtiene el consumo de créditos desglosado por día para un agente específico.

GET /api/v1/consumption/agent/{agentId}/dates

Obtener Consumo por Modelo

Obtiene el consumo de créditos desglosado por modelo de IA para un agente específico.

GET /api/v1/consumption/agent/{agentId}/models

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
`agentId`	string (UUID)	Sí	El identificador único del agente

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 de Consumo Diario

Código de Estado: 200 OK

Cuerpo de la Respuesta:

{
  "data": [
    {
      "date": "2024-01-15",
      "total_credits": 245
    },
    {
      "date": "2024-01-16",
      "total_credits": 312
    },
    {
      "date": "2024-01-17",
      "total_credits": 189
    },
    {
      "date": "2024-01-18",
      "total_credits": 401
    },
    {
      "date": "2024-01-19",
      "total_credits": 278
    }
  ]
}

Campos de la Respuesta (Diario)

Campo	Tipo	Descripción
`data`	array	Arreglo de objetos de consumo diario
`data[].date`	string (YYYY-MM-DD)	Fecha en formato ISO
`data[].total_credits`	integer	Total de créditos consumidos en esta fecha

Respuesta de Consumo por Modelo

Código de Estado: 200 OK

Cuerpo de la Respuesta:

{
  "data": [
    {
      "model_id": "880e8400-e29b-41d4-a716-446655440000",
      "name": "GPT-4",
      "total_credits": 8420
    },
    {
      "model_id": "990e8400-e29b-41d4-a716-446655440001",
      "name": "GPT-3.5 Turbo",
      "total_credits": 2180
    }
  ]
}

Campos de la Respuesta (Por Modelo)

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

Respuestas de Error

401 Unauthorized

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

403 Forbidden

Status: 403 Forbidden
{
  "error": "Agent does not belong to your organization"
}

404 Not Found

Status: 404 Not Found
{
  "error": "Agent not found"
}

500 Internal Server Error

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

Ejemplos de Uso

cURL

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

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

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

JavaScript (Fetch API)

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';
const agentId = '550e8400-e29b-41d4-a716-446655440000';

// Get daily consumption
fetch(`https://agentsgt.com/api/v1/consumption/agent/${agentId}/dates`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => {
    console.log('Daily consumption:');
    data.data.forEach(day => {
      console.log(`${day.date}: ${day.total_credits} credits`);
    });

    // Calculate total and average
    const total = data.data.reduce((sum, day) => sum + day.total_credits, 0);
    const average = total / data.data.length;
    console.log(`\nTotal: ${total} credits`);
    console.log(`Daily average: ${average.toFixed(2)} credits`);
  });

// Get consumption by model
fetch(`https://agentsgt.com/api/v1/consumption/agent/${agentId}/models`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => {
    console.log('\nConsumption by model:');
    data.data.forEach(model => {
      console.log(`${model.name}: ${model.total_credits} credits`);
    });
  });

// Fetch both metrics together
async function getAgentMetrics(agentId, from, to) {
  const params = new URLSearchParams();
  if (from) params.append('from', from);
  if (to) params.append('to', to);

  const [dailyResponse, modelsResponse] = await Promise.all([
    fetch(`https://agentsgt.com/api/v1/consumption/agent/${agentId}/dates?${params}`, {
      headers: { 'Authorization': `Bearer ${publicKey}:${secretKey}` }
    }),
    fetch(`https://agentsgt.com/api/v1/consumption/agent/${agentId}/models?${params}`, {
      headers: { 'Authorization': `Bearer ${publicKey}:${secretKey}` }
    })
  ]);

  const [daily, models] = await Promise.all([
    dailyResponse.json(),
    modelsResponse.json()
  ]);

  return { daily: daily.data, models: models.data };
}

// Usage
getAgentMetrics(agentId, '2024-01-01T00:00:00Z', '2024-01-31T23:59:59Z')
  .then(metrics => {
    console.log('Agent Metrics:', metrics);
  });

Python (Requests)

import requests
from datetime import datetime, timedelta
import matplotlib.pyplot as plt  # For visualization

public_key = 'pk_1234567890abcdef'
secret_key = 'sk_abcdef1234567890'
agent_id = '550e8400-e29b-41d4-a716-446655440000'

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

# Get daily consumption 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/agent/{agent_id}/dates',
    headers=headers,
    params=params
)

if response.status_code == 200:
    data = response.json()
    print("Daily Consumption (Last 30 days):")

    total_credits = 0
    for day in data['data']:
        print(f"  {day['date']}: {day['total_credits']} credits")
        total_credits += day['total_credits']

    average_per_day = total_credits / len(data['data']) if data['data'] else 0
    print(f"\nTotal: {total_credits} credits")
    print(f"Average per day: {average_per_day:.2f} credits")

    # Visualize daily consumption (optional)
    dates = [day['date'] for day in data['data']]
    credits = [day['total_credits'] for day in data['data']]

    # plt.figure(figsize=(12, 6))
    # plt.plot(dates, credits, marker='o')
    # plt.xlabel('Date')
    # plt.ylabel('Credits')
    # plt.title('Daily Credit Consumption')
    # plt.xticks(rotation=45)
    # plt.tight_layout()
    # plt.show()

# Get consumption by model
response = requests.get(
    f'https://agentsgt.com/api/v1/consumption/agent/{agent_id}/models',
    headers=headers,
    params=params
)

if response.status_code == 200:
    data = response.json()
    print("\nConsumption by Model:")

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

    total = sum(model['total_credits'] for model in sorted_models)

    for model in sorted_models:
        percentage = (model['total_credits'] / total * 100) if total > 0 else 0
        print(f"  {model['name']}: {model['total_credits']} credits ({percentage:.1f}%)")

Node.js (Axios)

const axios = require('axios');

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';
const agentId = '550e8400-e29b-41d4-a716-446655440000';

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

// Function to get comprehensive agent metrics
async function getAgentAnalytics(agentId, from, to) {
  try {
    const params = { from, to };

    // Fetch both endpoints in parallel
    const [dailyResponse, modelsResponse] = await Promise.all([
      axios.get(
        `https://agentsgt.com/api/v1/consumption/agent/${agentId}/dates`,
        { headers, params }
      ),
      axios.get(
        `https://agentsgt.com/api/v1/consumption/agent/${agentId}/models`,
        { headers, params }
      )
    ]);

    const daily = dailyResponse.data.data;
    const models = modelsResponse.data.data;

    // Calculate statistics
    const totalCredits = daily.reduce((sum, day) => sum + day.total_credits, 0);
    const averagePerDay = totalCredits / daily.length;
    const maxDay = daily.reduce((max, day) =>
      day.total_credits > max.total_credits ? day : max, daily[0]);
    const minDay = daily.reduce((min, day) =>
      day.total_credits < min.total_credits ? day : min, daily[0]);

    return {
      period: { from, to },
      daily,
      models,
      statistics: {
        totalCredits,
        averagePerDay,
        peakDay: maxDay,
        lowestDay: minDay,
        totalDays: daily.length
      }
    };
  } catch (error) {
    console.error('Error fetching agent analytics:', error.response?.data || error.message);
    throw error;
  }
}

// Get analytics 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();

getAgentAnalytics(agentId, startOfMonth, endOfMonth)
  .then(analytics => {
    console.log('Agent Analytics');
    console.log('===============');
    console.log(`Period: ${analytics.period.from} to ${analytics.period.to}`);
    console.log(`\nStatistics:`);
    console.log(`  Total Credits: ${analytics.statistics.totalCredits}`);
    console.log(`  Average per Day: ${analytics.statistics.averagePerDay.toFixed(2)}`);
    console.log(`  Peak Day: ${analytics.statistics.peakDay.date} (${analytics.statistics.peakDay.total_credits} credits)`);
    console.log(`  Lowest Day: ${analytics.statistics.lowestDay.date} (${analytics.statistics.lowestDay.total_credits} credits)`);

    console.log(`\nModel Usage:`);
    analytics.models.forEach(model => {
      const percentage = (model.total_credits / analytics.statistics.totalCredits * 100).toFixed(1);
      console.log(`  ${model.name}: ${model.total_credits} credits (${percentage}%)`);
    });

    console.log(`\nLast 7 Days:`);
    analytics.daily.slice(-7).forEach(day => {
      console.log(`  ${day.date}: ${day.total_credits} credits`);
    });
  });

Casos de Uso

Seguimiento de Rendimiento

Monitorea los patrones de uso del agente a lo largo del tiempo:

// Track daily usage to identify trends

Optimización de Costos

Identifica qué modelos consumen más créditos:

# Switch to more cost-effective models if appropriate

Planificación de Capacidad

Pronostica el uso futuro basándote en datos históricos:

// Calculate growth rate and predict future consumption

Detección de Anomalías

Detecta picos o caídas inusuales en el uso:

# Alert if consumption deviates significantly from average

Notas

Los datos de consumo diario están ordenados por fecha en orden ascendente
Si no se especifica un rango de fechas, se devuelve el consumo de todo el historial
Las fechas en la respuesta usan el formato YYYY-MM-DD
Los días con consumo cero no se incluyen en el desglose diario
El consumo por modelo muestra el uso agregado de todos los días del período
Si el modelo de un agente fue cambiado durante el período, ambos modelos aparecerán en el desglose
Los parámetros de fecha deben estar en formato ISO 8601 con zona horaria (por ejemplo, 2024-01-01T00:00:00Z)

Endpoints Relacionados

Obtener Métricas por Organización - Obtener métricas de consumo de toda la organización
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
Obtener Historial de Chat por Agente - Ver historial de conversaciones de este agente

Endpoints​

Obtener Consumo Diario​

Obtener Consumo por Modelo​

Autenticación​

Solicitud​

Parámetros de Ruta​

Encabezados​

Parámetros de Consulta​

Respuesta​

Respuesta de Consumo Diario​

Campos de la Respuesta (Diario)​

Respuesta de Consumo por Modelo​

Campos de la Respuesta (Por Modelo)​

Respuestas de Error​

401 Unauthorized​

403 Forbidden​

404 Not Found​

500 Internal Server Error​

Ejemplos de Uso​

cURL​

JavaScript (Fetch API)​

Python (Requests)​

Node.js (Axios)​

Casos de Uso​

Seguimiento de Rendimiento​

Optimización de Costos​

Planificación de Capacidad​

Detección de Anomalías​

Notas​

Endpoints Relacionados​