https://ai-search-api.nama.ai/api/v1/threads

Guia de Integração — API de Relatórios (Report)

Referência prática para consumir os endpoints de relatório do AI Search. Todos os endpoints retornam JSON (exceto o download, que retorna .xlsx) e exigem autenticação via Bearer token.

Índice

Autenticação
Permissões por Role
Visão Geral dos Endpoints
GET /api/v1/overview
GET /api/v1/credits_resume
GET /api/v1/token_resume
GET /api/v1/threads
GET /api/v1/report_download
Erros Comuns
Exemplos com cURL

1. Autenticação

Todos os endpoints exigem o header Authorization. Há duas formas de autenticar:

Bearer Token de usuário (mais comum)

Authorization: Bearer <seu_jwt_token>

Obtido no login via plataforma Nama. O token identifica o usuário e sua organização.

Token de Projeto

Authorization: Bearer <project_token>

Token fixo de um projeto específico, utilizado para integrações de serviço.

2. Permissões por Role

Os endpoints de relatório exigem roles específicos. A tabela abaixo mostra o acesso por role:

Role	`overview`	`credits_resume`	`token_resume`	`threads`	`report_download`
OWNER	✅	✅	✅	✅	✅
ADMIN	✅	✅	✅	✅	✅
EDITOR	❌	✅	❌	❌	❌
VIEWER	❌	❌	❌	❌	❌

Tentativas de acesso sem permissão retornam 403 Forbidden.

3. Visão Geral dos Endpoints

Endpoint	Método	O que retorna
`/api/v1/overview`	GET	Dashboard geral: plano, limites, uso de créditos e projetos
`/api/v1/credits_resume`	GET	Consumo de créditos no período com histórico e top datamodels
`/api/v1/token_resume`	GET	Consumo de tokens no período com histórico e top datamodels
`/api/v1/threads`	GET	Lista paginada de conversas com suas interações
`/api/v1/report_download`	GET	Download de relatório completo em formato `.xlsx`

4. GET /api/v1/overview

Retorna um painel consolidado da organização: plano contratado, limites, uso de créditos e contadores de projetos.

Query Parameters

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`start_date`	`YYYY-MM-DD`	Não	1º dia do mês atual	Início do período
`end_date`	`YYYY-MM-DD`	Não	Último dia do mês atual	Fim do período

Exemplo de Requisição

GET /api/v1/overview?start_date=2026-03-01&end_date=2026-03-31
Authorization: Bearer <token>

Resposta de Sucesso (`200 OK`)

{
  "user": "[email protected]",
  "plan": "Pro",
  "end_date": "2026-03-31",
  "plan_interval": "monthly",
  "trial_period": false,
  "did_trial_period": true,
  "datamodel_count": "3 / 10",
  "private_smartpage_count": "2 / 5",
  "private_smartpage_limit": 5,
  "public_smartpage_count": "1 / 3",
  "public_smartpage_limit": 3,
  "private_smartpage_user_count": "4 / 20",
  "private_smartpage_user_limit": 20,
  "credit_limit": 1000000,
  "addon": {
    "addon_name": "Extra Credits Pack",
    "credits": 500000
  },
  "total_credit_used": 234567,
  "overflow_credits_usage": 0,
  "percentage_credit_used": 23.46,
  "project_data": {
    "datamodels": 3,
    "datasets": 5,
    "contents": 120,
    "smartpages": 3,
    "private_smartpages": 2,
    "public_smartpages": 1,
    "private_smartpage_users": 4,
    "indexed_tokens_limit": 5000000,
    "total_indexed_tokens": 1200000,
    "total_processed_tokens": 234567,
    "total_api_requests": 890
  }
}

Campos Principais

Campo	Descrição
`plan`	Nome do plano ativo
`plan_interval`	`monthly` ou `yearly`
`credit_limit`	Limite total de créditos do plano
`total_credit_used`	Total de créditos consumidos no período
`percentage_credit_used`	Percentual do limite de créditos utilizado
`overflow_credits_usage`	Créditos consumidos além do limite (excedente)
`addon`	Pacote adicional de créditos contratado (ou `null`)
`project_data`	Contadores de recursos do projeto (datamodels, datasets, tokens, etc.)

5. GET /api/v1/credits_resume

Retorna o histórico de consumo de créditos (tokens com fee) no período, comparação com o período anterior e os top 5 datamodels por consumo.

Query Parameters

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`start_date`	`YYYY-MM-DD`	Não	1º dia do mês atual	Mínimo: `2025-02-01`
`end_date`	`YYYY-MM-DD`	Não	Último dia do mês atual	—

Exemplo de Requisição

GET /api/v1/credits_resume?start_date=2026-03-01&end_date=2026-03-31
Authorization: Bearer <token>

Resposta de Sucesso (`200 OK`)

{
  "credits": [
    {
      "date": "2026-03-01",
      "workspace_credits": 1200,
      "smartpage_credits": 800,
      "api_credits": 12345
    },
    {
      "date": "2026-03-02",
      "workspace_credits": 900,
      "smartpage_credits": 600,
      "api_credits": 9800
    }
  ],
  "credits_usage_details": {
    "total_credits_used": 234567,
    "credits_previous_period_comparison": {
      "current_period_usage": 234567,
      "previous_period_usage": 198000,
      "percent_difference": 18.47
    },
  },
  "top_datamodels_by_credit_usage": [
    {
      "name": "produto-faq",
      "dataset": "base-conhecimento",
      "credits_used": 89000,
      "tokens_processed": 80000,
      "api_requests": 320,
      "percentage": 37.95
    }
  ]
}

Campos Principais

Campo	Descrição
`credits`	Array com consumo por data (granularidade automática)
`credits[].workspace_credits`	Créditos consumidos via workspace
`credits[].smartpage_credits`	Créditos consumidos via smartpage
`credits[].api_credits`	Créditos consumidos via API
`total_credits_used`	Total do período selecionado
`percent_difference`	Variação % vs. período anterior (positivo = aumento)
`top_datamodels_by_credit_usage`	Top 5 datamodels com maior consumo

6. GET /api/v1/token_resume

Retorna o histórico de tokens processados no período, comparação com o período anterior e os top 5 datamodels por uso de tokens.

Query Parameters

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`start_date`	`YYYY-MM-DD`	Não	1º dia do mês atual	Mínimo: `2025-02-01`
`end_date`	`YYYY-MM-DD`	Não	Último dia do mês atual	—
`datamodel_name`	string	Não	—	Filtra por datamodel específico
`offset`	int	Não	`0`	Offset para paginação
`limit`	int	Não	`30`	Limite de itens por página

Exemplo de Requisição

GET /api/v1/token_resume?start_date=2026-03-01&end_date=2026-03-31
Authorization: Bearer <token>

Resposta de Sucesso (`200 OK`)

{
  "tokens": [
    {
      "date": "2026-03-01",
      "processed_tokens": 45000,
      "api_requests": 120
    },
    {
      "date": "2026-03-02",
      "processed_tokens": 38000,
      "api_requests": 98
    }
  ],
  "token_usage_details": {
    "total_tokens_processed": 450000,
    "tokens_previous_period_comparison": {
      "current_period": 450000,
      "previous_period": 390000
    },
    "usage_by_origin": {
      "smartpage": 90000,
      "api": 340000,
      "workspace": 20000
    }
  },
  "top_datamodels_by_token_usage": [
    {
      "name": "produto-faq",
      "dataset": "base-conhecimento",
      "tokens_processed": 180000,
      "api_requests": 350,
      "percentage": 40.0
    }
  ]
}

Diferença entre Tokens e Créditos

Tokens (token_resume): volume bruto de tokens processados pelo modelo de linguagem.
Créditos (credits_resume): tokens com multiplicador de fee aplicado (varia por modelo e tipo de operação). É a unidade de cobrança efetiva.

7. GET /api/v1/threads

Lista paginada das conversas (threads) da organização, com todas as interações de cada conversa. Ideal para análise de qualidade, auditoria e monitoramento de uso.

Query Parameters

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`start_date`	`YYYY-MM-DD`	Não	`2025-02-01`	Início do período
`end_date`	`YYYY-MM-DD`	Não	—	Fim do período (sem limite padrão)
`question`	string	Não	—	Busca textual no campo pergunta (case-insensitive)
`evaluation`	string (CSV)	Não	—	Filtra por avaliação: `positive`, `negative`, `neutral`
`feedback`	`true`/`false`	Não	—	`true` = apenas com feedback; `false` = apenas sem feedback
`datamodel`	string (CSV)	Não	—	Nomes de datamodels separados por vírgula
`interaction_types`	string (CSV)	Não	—	`search`, `stream`, `deepsearch`
`limit`	int	Não	`-`	Máximo de threads por página
`offset`	int	Não	`0`	Offset para paginação

Exemplo de Requisição

# Listar threads com avaliação negativa do datamodel "suporte"
GET /api/v1/threads?evaluation=negative&datamodel=suporte&limit=50&offset=0
Authorization: Bearer <token>

Resposta de Sucesso (`200 OK`)

{
  "count": 42,
  "next": true,
  "previous": false,
  "results": [
    {
      "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "conversation_identifier": "user-session-xyz",
      "created_at": "2026-03-10T14:00:00Z",
      "updated_at": "2026-03-10T14:05:32Z",
      "interactions": [
        {
          "identifier": "8d2e1c3a-0001-4abc-b000-000000000001",
          "type": "stream",
          "interaction_type": "Stream",
          "question": "Qual é o prazo de entrega?",
          "content": "O prazo padrão é de 5 a 7 dias úteis...",
          "datamodel": "suporte",
          "dataset": "politicas-entrega",
          "generative_model": "gpt-4o",
          "preset": "default",
          "preset_id": 1,
          "project_id": 7,
          "project_name": "Portal Suporte",
          "total_tokens": 520,
          "total_tokens_with_fee": 572,
          "prompt_tokens": 320,
          "completion_tokens": 200,
          "evaluation": "positive",
          "feedback": "Resposta clara e completa",
          "feedback_options": null,
          "user": {
            "name": "Maria Silva",
            "email": "[email protected]"
          },
          "api_call_id": 1042,
          "created_at": "2026-03-10T14:00:00Z",
          "updated_at": "2026-03-10T14:00:05Z",
          "extra": {},
          "search": {},
          "user_prompt": "Qual é o prazo de entrega?",
          "template_prompt": "Você é um assistente de suporte..."
        }
      ]
    }
  ]
}

Campos Principais

Campo	Descrição
`count`	Total de threads no filtro aplicado
`next`	`true` se há mais páginas; `false` caso contrário
`results[].conversation_id`	UUID único da conversa
`results[].interactions`	Array com todas as interações da conversa
`interactions[].type`	Tipo da interação: `search`, `stream`, `deepsearch`
`interactions[].question`	Pergunta feita pelo usuário
`interactions[].content`	Resposta gerada pelo modelo
`interactions[].evaluation`	Avaliação do usuário: `positive`, `negative`, `neutral` ou `null`
`interactions[].feedback`	Texto de feedback livre deixado pelo usuário
`interactions[].total_tokens`	Tokens totais consumidos na interação
`interactions[].total_tokens_with_fee`	Tokens com multiplicador (= créditos usados)
`interactions[].user`	Dados do usuário que fez a pergunta
`interactions[].generative_model`	Modelo de LLM utilizado (ex: `gpt-4o`)

8. GET /api/v1/report_download

Gera e faz download de um arquivo Excel (.xlsx) com até três abas: resumo de créditos, resumo de tokens e lista de threads.

Query Parameters

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`start_date`	`YYYY-MM-DD`	Não	`2025-02-01`	Início do período
`end_date`	`YYYY-MM-DD`	Não	Data atual	Fim do período
`section`	string	Não	`all`	`all`, `credits`, `tokens` ou `threads`
`datamodel_id`	int	Não	—	Filtra por ID do datamodel
`datamodel_name`	string	Não	—	Filtra por nome do datamodel
`interaction_types`	string (CSV)	Não	—	`search`, `stream`, `deepsearch`
`language`	`en` / `pt`	Não	`en`	Idioma dos cabeçalhos das colunas
`limit`	int	Não	`10000`	Limite de threads incluídas na aba Threads

Abas do Excel gerado

Aba	Disponível quando `section`
Credits Resume	`all` ou `credits`
Tokens Resume	`all` ou `tokens`
Threads	`all` ou `threads`

Exemplo de Requisição

# Baixar apenas a aba de threads em português
GET /api/v1/report_download?section=threads&start_date=2026-03-01&language=pt
Authorization: Bearer <token>

Resposta de Sucesso (`200 OK`)

Retorna um arquivo binário com os headers:

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="minha-org_report_2026-03-01_2026-03-31.xlsx"

Exemplo: salvar o arquivo com cURL

curl -X GET \\
  "<https://api.nama.ai/api/v1/report_download?section=all&start_date=2026-03-01&end_date=2026-03-31&language=pt>" \\
  -H "Authorization: Bearer <seu_token>" \\
  --output relatorio-marco-2026.xlsx

9. Erros Comuns

Código	Significado	Causa mais comum
`401 Unauthorized`	Token ausente ou inválido	Header `Authorization` não enviado ou token expirado
`403 Forbidden`	Sem permissão	Role do usuário não tem acesso ao endpoint
`400 Bad Request`	Parâmetro inválido	Formato de data incorreto (usar `YYYY-MM-DD`) ou parâmetro desconhecido
`404 Not Found`	Recurso não encontrado	Organização ou projeto não existe para o token informado
`500 Internal Server Error`	Erro interno	Problema no servidor — contate o suporte

Formato de erro

{
  "detail": "Você não tem permissão para realizar esta ação."
}

10. Exemplos com cURL

Overview do mês atual

curl -X GET \\
  "<https://api.nama.ai/api/v1/overview>" \\
  -H "Authorization: Bearer <seu_token>"

Consumo de créditos de um datamodel específico

curl -X GET \\
  "<https://api.nama.ai/api/v1/credits_resume?start_date=2026-03-01&end_date=2026-03-31&datamodel_name=suporte>" \\
  -H "Authorization: Bearer <seu_token>"

Threads com avaliação negativa nos últimos 7 dias

curl -X GET \\
  "<https://api.nama.ai/api/v1/threads?start_date=2026-03-09&end_date=2026-03-16&evaluation=negative&limit=100>" \\
  -H "Authorization: Bearer <seu_token>"

Threads filtrando por múltiplos datamodels e tipo de interação

curl -X GET \\
  "<https://api.nama.ai/api/v1/threads?datamodel=suporte,vendas&interaction_types=stream,deepsearch&limit=200>" \\
  -H "Authorization: Bearer <seu_token>"

Download do relatório completo

curl -X GET \\
  "<https://api.nama.ai/api/v1/report_download?section=all&language=pt&start_date=2026-03-01&end_date=2026-03-31>" \\
  -H "Authorization: Bearer <seu_token>" \\
  --output relatorio.xlsx

Guia de Integração — API de Relatórios (Report)

Índice

1. Autenticação

Bearer Token de usuário (mais comum)

Token de Projeto

2. Permissões por Role

3. Visão Geral dos Endpoints

4. GET /api/v1/overview

Query Parameters

Exemplo de Requisição

Resposta de Sucesso (200 OK)

Campos Principais

5. GET /api/v1/credits_resume

Query Parameters

Exemplo de Requisição

Resposta de Sucesso (200 OK)

Campos Principais

6. GET /api/v1/token_resume

Query Parameters

Exemplo de Requisição

Resposta de Sucesso (200 OK)

Diferença entre Tokens e Créditos

7. GET /api/v1/threads

Query Parameters

Exemplo de Requisição

Resposta de Sucesso (200 OK)

Campos Principais

8. GET /api/v1/report_download

Query Parameters

Abas do Excel gerado

Exemplo de Requisição

Resposta de Sucesso (200 OK)

Exemplo: salvar o arquivo com cURL

9. Erros Comuns

Formato de erro

10. Exemplos com cURL

Overview do mês atual

Consumo de créditos de um datamodel específico

Threads com avaliação negativa nos últimos 7 dias

Threads filtrando por múltiplos datamodels e tipo de interação

Download do relatório completo

Resposta de Sucesso (`200 OK`)

Resposta de Sucesso (`200 OK`)

Resposta de Sucesso (`200 OK`)

Resposta de Sucesso (`200 OK`)

Resposta de Sucesso (`200 OK`)