Tokiadocs
⌘K

Sessions

Agrupe requests da mesma conversa (chatbot, agente, fluxo multi-step) e veja custo total, tokens, modelos usados e duração no dashboard.

Por que usar Sessions

  • Debug: uma session = uma conversa. Em vez de 20 linhas soltas em /usage, vê 1 entrada com tudo dentro.
  • Atribuição de custo: "Quanto custou aquele atendimento do cliente X?" — abre a session correspondente.
  • Comparação multi-modelo: session que usou gpt-4o-mini em algumas mensagens e claude-sonnet-46 em outras aparece com ambos listados.
  • Integração natural com Prompts library: cada run do playground cria uma session com prefixo prompt-<id>-<ts>.

Como funciona (3 passos)

  1. Gere um UUID por conversa no seu cliente (ou use o conversation_id que você já tem).
  2. Envie o header x-tokia-session-id: <uuid> em cada POST /v1/chat/completions daquela conversa.
  3. Abra /dashboard/sessions e veja os requests agrupados. Clique em uma session pra ver eventos cronológicos.

Exemplo Python

from openai import OpenAI
import uuid

tokia = OpenAI(
    api_key="sk-...",
    base_url="https://api.usetokia.com/v1",
)

session_id = str(uuid.uuid4())  # 1 UUID por conversa

# Mensagem 1 da conversa
resp1 = tokia.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Oi"}],
    extra_headers={"x-tokia-session-id": session_id},
)

# Mensagem 2 da mesma conversa — REUSA o session_id
resp2 = tokia.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Oi"},
        {"role": "assistant", "content": resp1.choices[0].message.content},
        {"role": "user", "content": "Pode resumir?"},
    ],
    extra_headers={"x-tokia-session-id": session_id},
)

# /dashboard/sessions vai mostrar 1 session com 2 requests

Exemplo JavaScript / Node

import OpenAI from "openai";
import { randomUUID } from "crypto";

const tokia = new OpenAI({
  apiKey: process.env.TOKIA_API_KEY,
  baseURL: "https://api.usetokia.com/v1",
});

const sessionId = randomUUID();

await tokia.chat.completions.create(
  { model: "claude-sonnet-46", messages: [{ role: "user", content: "Oi" }] },
  { headers: { "x-tokia-session-id": sessionId } },
);

Exemplo curl

curl https://api.usetokia.com/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -H "x-tokia-session-id: $(uuidgen)" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Oi"}]}'

Endpoints API

  • GET /me/sessions?days=30&limit=100 — lista sessions (default últimos 30 dias)
  • GET /me/sessions/<id> — eventos cronológicos da session

Limites

  • session_id aceita até 80 chars (uuid, slug, conversation_id do cliente — qualquer string)
  • Histórico exibido: últimos 90 dias (configurável via ?days=N)
  • Máximo 500 sessions por chamada GET /me/sessions
  • Máximo 500 eventos por session no GET /me/sessions/:id

Veja também