Obtener Métricas por Identificador

Recupera métricas de uso y datos de consumo para un usuario o identificador de sesión específico.

Endpoint

GET /api/v1/consumption/identifier/{identifier}/dates

Autenticación

Este endpoint requiere 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
identifier	string	Sí	El identificador único del usuario o sesión (por ejemplo, correo electrónico, ID de usuario, número de teléfono)

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 Exitosa

Código de Estado: 200 OK

Cuerpo de la Respuesta:

{
  "data": [
    {
      "date": "2024-01-15",
      "total_credits": 12
    },
    {
      "date": "2024-01-16",
      "total_credits": 18
    },
    {
      "date": "2024-01-17",
      "total_credits": 9
    },
    {
      "date": "2024-01-18",
      "total_credits": 21
    },
    {
      "date": "2024-01-19",
      "total_credits": 15
    }
  ]
}

Campos de la Respuesta

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 para este identificador

Respuestas de Error

401 Unauthorized

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

400 Bad Request

Identificador Faltante:

Status: 400 Bad Request
{
  "error": "Identifier parameter is required"
}

404 Not Found

No se Encontraron Datos:

Status: 404 Not Found
{
  "error": "No consumption data found for this identifier"
}

500 Internal Server Error

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

Ejemplos de Uso

cURL

# Get consumption for an identifier
curl -X GET "https://agentsgt.com/api/v1/consumption/identifier/user@example.com/dates" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

# With URL encoding for email identifier
curl -X GET "https://agentsgt.com/api/v1/consumption/identifier/user%40example.com/dates" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

# Get consumption for date range
curl -X GET "https://agentsgt.com/api/v1/consumption/identifier/user@example.com/dates?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

# Using phone number as identifier
curl -X GET "https://agentsgt.com/api/v1/consumption/identifier/%2B15551234567/dates" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

JavaScript (Fetch API)

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';
const identifier = 'user@example.com';

// URL encode the identifier
const encodedIdentifier = encodeURIComponent(identifier);

// Get daily consumption
fetch(`https://agentsgt.com/api/v1/consumption/identifier/${encodedIdentifier}/dates`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => {
    console.log(`Consumption for: ${identifier}`);
    console.log('Daily breakdown:');

    let totalCredits = 0;
    data.data.forEach(day => {
      console.log(`  ${day.date}: ${day.total_credits} credits`);
      totalCredits += day.total_credits;
    });

    console.log(`\nTotal: ${totalCredits} credits`);
    console.log(`Average per day: ${(totalCredits / data.data.length).toFixed(2)} credits`);
  })
  .catch(error => {
    console.error('Error:', error);
  });

// Get consumption 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/identifier/${encodedIdentifier}/dates?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => {
    // Find peak usage day
    const peakDay = data.data.reduce((max, day) =>
      day.total_credits > max.total_credits ? day : max,
      data.data[0]
    );

    console.log(`Peak usage: ${peakDay.date} with ${peakDay.total_credits} credits`);
  });

Python (Requests)

import requests
from urllib.parse import quote
from datetime import datetime, timedelta

public_key = 'pk_1234567890abcdef'
secret_key = 'sk_abcdef1234567890'
identifier = 'user@example.com'

# URL encode the identifier
encoded_identifier = quote(identifier)

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

# Get 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/identifier/{encoded_identifier}/dates',
    headers=headers,
    params=params
)

if response.status_code == 200:
    data = response.json()
    print(f"Consumption for {identifier} (Last 30 days):\n")

    total_credits = 0
    daily_data = data['data']

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

    if daily_data:
        average = total_credits / len(daily_data)
        print(f"\nSummary:")
        print(f"  Total credits: {total_credits}")
        print(f"  Average per day: {average:.2f}")
        print(f"  Days active: {len(daily_data)}")

        # Find trends
        peak_day = max(daily_data, key=lambda x: x['total_credits'])
        print(f"  Peak day: {peak_day['date']} ({peak_day['total_credits']} credits)")

elif response.status_code == 404:
    print(f"No consumption data found for {identifier}")
else:
    print(f"Error: {response.status_code} - {response.json()}")

# Track multiple users
def get_user_consumption_summary(identifiers, from_date=None, to_date=None):
    """Get consumption summary for multiple users."""
    results = {}

    for identifier in identifiers:
        encoded = quote(identifier)
        params = {}
        if from_date:
            params['from'] = from_date
        if to_date:
            params['to'] = to_date

        response = requests.get(
            f'https://agentsgt.com/api/v1/consumption/identifier/{encoded}/dates',
            headers=headers,
            params=params
        )

        if response.status_code == 200:
            data = response.json()
            total = sum(day['total_credits'] for day in data['data'])
            results[identifier] = {
                'total_credits': total,
                'days_active': len(data['data']),
                'daily_data': data['data']
            }
        else:
            results[identifier] = {'error': response.status_code}

    return results

# Usage
users = ['user1@example.com', 'user2@example.com', 'user3@example.com']
summary = get_user_consumption_summary(
    users,
    from_date='2024-01-01T00:00:00Z',
    to_date='2024-01-31T23:59:59Z'
)

print("\nMulti-user Summary:")
for user, stats in summary.items():
    if 'error' not in stats:
        print(f"  {user}: {stats['total_credits']} credits over {stats['days_active']} days")
    else:
        print(f"  {user}: Error {stats['error']}")

Node.js (Axios)

const axios = require('axios');

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';

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

// Function to get user consumption metrics
async function getUserConsumption(identifier, from, to) {
  const encodedIdentifier = encodeURIComponent(identifier);
  const params = {};
  if (from) params.from = from;
  if (to) params.to = to;

  try {
    const response = await axios.get(
      `https://agentsgt.com/api/v1/consumption/identifier/${encodedIdentifier}/dates`,
      { headers, params }
    );

    const daily = response.data.data;
    const totalCredits = daily.reduce((sum, day) => sum + day.total_credits, 0);
    const averagePerDay = totalCredits / daily.length;

    return {
      identifier,
      daily,
      statistics: {
        totalCredits,
        averagePerDay,
        daysActive: daily.length,
        peakDay: daily.reduce((max, day) =>
          day.total_credits > max.total_credits ? day : max,
          daily[0]
        )
      }
    };
  } catch (error) {
    console.error(`Error fetching consumption for ${identifier}:`,
      error.response?.data || error.message);
    throw error;
  }
}

// Get consumption for a user
getUserConsumption('user@example.com', '2024-01-01T00:00:00Z', '2024-01-31T23:59:59Z')
  .then(metrics => {
    console.log(`\nConsumption Metrics for ${metrics.identifier}`);
    console.log('='.repeat(50));
    console.log(`Total Credits: ${metrics.statistics.totalCredits}`);
    console.log(`Days Active: ${metrics.statistics.daysActive}`);
    console.log(`Average per Day: ${metrics.statistics.averagePerDay.toFixed(2)}`);
    console.log(`Peak Day: ${metrics.statistics.peakDay.date} (${metrics.statistics.peakDay.total_credits} credits)`);

    console.log('\nLast 7 Days:');
    metrics.daily.slice(-7).forEach(day => {
      const bar = '█'.repeat(Math.ceil(day.total_credits / 2));
      console.log(`  ${day.date}: ${bar} ${day.total_credits}`);
    });
  });

// Compare multiple users
async function compareUserConsumption(identifiers, from, to) {
  const results = await Promise.all(
    identifiers.map(id => getUserConsumption(id, from, to).catch(err => ({
      identifier: id,
      error: err.message
    })))
  );

  console.log('\nUser Consumption Comparison');
  console.log('='.repeat(50));

  // Filter successful results
  const successful = results.filter(r => !r.error);

  // Sort by total consumption
  successful.sort((a, b) => b.statistics.totalCredits - a.statistics.totalCredits);

  successful.forEach((user, index) => {
    console.log(`${index + 1}. ${user.identifier}`);
    console.log(`   Total: ${user.statistics.totalCredits} credits`);
    console.log(`   Avg/day: ${user.statistics.averagePerDay.toFixed(2)}`);
  });

  // Show errors
  const errors = results.filter(r => r.error);
  if (errors.length > 0) {
    console.log('\nErrors:');
    errors.forEach(err => {
      console.log(`  ${err.identifier}: ${err.error}`);
    });
  }

  return results;
}

// Usage
const users = ['user1@example.com', 'user2@example.com', 'user3@example.com'];
compareUserConsumption(users, '2024-01-01T00:00:00Z', '2024-01-31T23:59:59Z');

Casos de Uso

Seguimiento de Actividad del Usuario

Monitorea la interacción individual de los usuarios con tus agentes:

// Track which users are most active

Éxito del Cliente

Identifica usuarios avanzados y aquellos que podrían necesitar asistencia:

# Alert customer success team when user activity changes significantly

Facturación por Usuario

Rastrea el consumo para facturación basada en usuarios:

// Calculate credits consumed per user for invoicing

Prevención de Abandono

Detecta patrones de interacción decreciente:

# Identify users with declining usage

Notas

• El identificador es el mismo valor que proporcionas al enviar mensajes a los agentes (por ejemplo, correo electrónico, ID de usuario, número de teléfono)
• 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
• Los días con consumo cero no se incluyen en la respuesta
• Los identificadores deben codificarse para URL, especialmente si contienen caracteres especiales (por ejemplo, @ en correos electrónicos, + en números de teléfono)
• Este endpoint devuelve el consumo de todos los agentes con los que el usuario ha interactuado
• Los parámetros de fecha deben estar en formato ISO 8601 con zona horaria (por ejemplo, 2024-01-01T00:00:00Z)
• El identificador coincide con el campo external_user_id en el historial de chat

Endpoints Relacionados

• Obtener Métricas por Agente - Obtener métricas detalladas de un agente específico
• Obtener Métricas por Organización - Obtener métricas de consumo de toda la organización
• Obtener Historial de Chat por Identificador - Ver historial de conversaciones de este identificador