Métricas

Dados agregados de visibilidade, Share of Voice, citações e posições da sua marca e dos seus concorrentes, prontos a representar em gráficos. Todos os endpoints aceitam os filtros comuns e o parâmetro output descrito em Conceitos básicos.

GET`/metrics/timeseries`

Devolve séries temporais para uma ou mais métricas, agrupadas por interveniente (o seu projeto + concorrentes selecionados). Os valores semanais e mensais seguem a semântica de período acima. Os filtros opcionais prompt_type (intenção de pesquisa) e brand_kind limitam cada métrica a uma categoria de prompt.

GET`/metrics/summary`

Agrega por interveniente e métrica (total/min/max/last). Ideal para cartões de KPI.

GET`/metrics/prompt_summary`

Devolve métricas agregadas por prompt, paginadas (responses, mentions, citations, mention_rate, citation_rate, avg_mention_position, avg_position). Suporta breakdown=model para adicionar a dimensão do modelo de IA a cada linha, devolvendo métricas por prompt e por modelo. Parâmetros: sort (responses, mentions, citations, mention_rate ou visibility, citation_rate, avg_mention_position, avg_position), sort_dir (asc/desc), breakdown (model), page, per_page (máx. 100).

GET`/metrics/sov`

Share of Voice com base em menções, alinhado com a Visão geral.

over_time: para cada data, SOV = (actor_mentions / sum_all_mentions) × 100. Se a soma diária for 0, o último valor é mantido (sticky).
current: utiliza a data mais recente com total diferente de zero; se não existir, utiliza os totais de todo o intervalo.
breakdown: os 4 principais intervenientes + uma linha Outros agregada (e uma lista others detalhada).
periods e sample: cada período indica as mentions usadas para calcular as respetivas percentagens, um indicador partial, um nível de confidence (none sem menções, low abaixo de 30, medium abaixo de 100, high a partir de 100) e a margin_of_error, a margem de erro de 95% no pior caso, em pontos percentuais (98 dividido pela raiz quadrada de mentions, cerca de 18 pontos com 30 menções e 10 com 100; null sem menções). sample repete o período usado para calcular as percentagens current, ou é null quando o período não tem menções.

GET`/metrics/top_sources`

Classifica os domínios de origem pelo número de respostas e pela taxa média de menções (% de execuções que apresentaram esse domínio).

O conjunto de dados inclui fontes não rejeitadas associadas a execuções de prompt dentro da janela e dos filtros atuais.
total_responses: número de execuções de prompt únicas que produziram pelo menos uma fonte nesse domínio.
avg_mention_rate (também devolvido como avg_visibility): (número de linhas de origem do domínio / total de execuções) × 100.
Ordenação: sort=total_responses (predefinido), sort=avg_mention_rate ou sort=avg_visibility.
Paginação: page (>=1), per_page (predefinido 20, máximo 100).
Filtrar por domínio: query (LIKE sem distinção de maiúsculas/minúsculas), por exemplo query=github.

Exemplos de código

Download: OpenAPI Swagger Postman

Perguntar à IA: Abrir no ChatGPT Abrir no Claude Ver como Markdown

Linguagem

Request

curl -X GET -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.llmpulse.ai/api/v1/metrics/timeseries?project_id=PROJECT_ID&metrics=mentions,visibility&granularity=day&range=30"

const response = await fetch("https://api.llmpulse.ai/api/v1/metrics/timeseries?project_id=PROJECT_ID&metrics=mentions,visibility&granularity=day&range=30", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.llmpulse.ai/api/v1/metrics/timeseries?project_id=PROJECT_ID&metrics=mentions,visibility&granularity=day&range=30",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

require 'httparty'

response = HTTParty.get(
  "https://api.llmpulse.ai/api/v1/metrics/timeseries?project_id=PROJECT_ID&metrics=mentions,visibility&granularity=day&range=30",
  headers: { "Authorization" => "Bearer YOUR_API_KEY" }
)
data = response.parsed_response

req, _ := http.NewRequest("GET", "https://api.llmpulse.ai/api/v1/metrics/timeseries?project_id=PROJECT_ID&metrics=mentions,visibility&granularity=day&range=30", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.llmpulse.ai/api/v1/metrics/timeseries?project_id=PROJECT_ID&metrics=mentions,visibility&granularity=day&range=30', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/metrics/timeseries?project_id=PROJECT_ID&metrics=mentions,visibility&granularity=day&range=30"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Response

{
  "project_id":"...",
  "from":"2025-02-01T00:00:00Z",
  "to":"2025-03-02T23:59:59Z",
  "granularity":"day",
  "filters":{ ... },
  "series":{
    "mentions":[
      { "actor": { "type":"project","id":1,"name":"Acme","domain":null }, "metric":"mentions",
        "data":[ { "date":"2025-02-01","value":12 }, ... ] },
      { "actor": { "type":"competitor","id":5,"name":"Contoso","domain":"contoso.com" }, "metric":"mentions", "data":[ ... ] }
    ],
    "visibility":[ ... ],
    "citations":[ ... ],
    "avg_position":[ ... ]
  },
  "request_id":"..."
}

Request

curl -X GET -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.llmpulse.ai/api/v1/metrics/summary?project_id=PROJECT_ID&metrics=mentions,citations&granularity=day&range=30"

const response = await fetch("https://api.llmpulse.ai/api/v1/metrics/summary?project_id=PROJECT_ID&metrics=mentions,citations&granularity=day&range=30", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.llmpulse.ai/api/v1/metrics/summary?project_id=PROJECT_ID&metrics=mentions,citations&granularity=day&range=30",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

require 'httparty'

response = HTTParty.get(
  "https://api.llmpulse.ai/api/v1/metrics/summary?project_id=PROJECT_ID&metrics=mentions,citations&granularity=day&range=30",
  headers: { "Authorization" => "Bearer YOUR_API_KEY" }
)
data = response.parsed_response

req, _ := http.NewRequest("GET", "https://api.llmpulse.ai/api/v1/metrics/summary?project_id=PROJECT_ID&metrics=mentions,citations&granularity=day&range=30", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.llmpulse.ai/api/v1/metrics/summary?project_id=PROJECT_ID&metrics=mentions,citations&granularity=day&range=30', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/metrics/summary?project_id=PROJECT_ID&metrics=mentions,citations&granularity=day&range=30"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Response

{
  "series": { ... },
  "summary": {
    "mentions": [
      { "actor": { "type":"project","id":1,"name":"Acme" }, "total":1450, "min":0, "max":120, "last":34 }
    ],
    "avg_position": [
      { "actor": { "type":"project","id":1,"name":"Acme" }, "total":3.42, "min":2.1, "max":5.3, "last":3.8 }
    ]
  }
}

Request

curl -X GET -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.llmpulse.ai/api/v1/metrics/prompt_summary?project_id=PROJECT_ID&range=30&sort=visibility&sort_dir=desc&per_page=50"

const response = await fetch("https://api.llmpulse.ai/api/v1/metrics/prompt_summary?project_id=PROJECT_ID&range=30&sort=visibility&sort_dir=desc&per_page=50", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.llmpulse.ai/api/v1/metrics/prompt_summary?project_id=PROJECT_ID&range=30&sort=visibility&sort_dir=desc&per_page=50",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

require 'httparty'

response = HTTParty.get(
  "https://api.llmpulse.ai/api/v1/metrics/prompt_summary?project_id=PROJECT_ID&range=30&sort=visibility&sort_dir=desc&per_page=50",
  headers: { "Authorization" => "Bearer YOUR_API_KEY" }
)
data = response.parsed_response

req, _ := http.NewRequest("GET", "https://api.llmpulse.ai/api/v1/metrics/prompt_summary?project_id=PROJECT_ID&range=30&sort=visibility&sort_dir=desc&per_page=50", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.llmpulse.ai/api/v1/metrics/prompt_summary?project_id=PROJECT_ID&range=30&sort=visibility&sort_dir=desc&per_page=50', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/metrics/prompt_summary?project_id=PROJECT_ID&range=30&sort=visibility&sort_dir=desc&per_page=50"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Response

{
  "project_id": 1,
  "breakdown": "model",
  "sort": "mention_rate", "sort_dir": "desc",
  "page": 1, "per_page": 50, "total": 230,
  "data": [
    {
      "prompt_id": 123,
      "prompt_text": "best CRM software",
      "model": "chatgpt",
      "responses": 50,
      "mentions": 30,
      "citations": 15,
      "visibility": 60.0,
      "mention_rate": 60.0,
      "citation_rate": 30.0,
      "avg_mention_position": 2.35,
      "avg_position": 3.1
    }
  ]
}

Request

curl -X GET -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.llmpulse.ai/api/v1/metrics/sov?project_id=PROJECT_ID&range=30"

const response = await fetch("https://api.llmpulse.ai/api/v1/metrics/sov?project_id=PROJECT_ID&range=30", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.llmpulse.ai/api/v1/metrics/sov?project_id=PROJECT_ID&range=30",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

require 'httparty'

response = HTTParty.get(
  "https://api.llmpulse.ai/api/v1/metrics/sov?project_id=PROJECT_ID&range=30",
  headers: { "Authorization" => "Bearer YOUR_API_KEY" }
)
data = response.parsed_response

req, _ := http.NewRequest("GET", "https://api.llmpulse.ai/api/v1/metrics/sov?project_id=PROJECT_ID&range=30", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.llmpulse.ai/api/v1/metrics/sov?project_id=PROJECT_ID&range=30', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/metrics/sov?project_id=PROJECT_ID&range=30"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Response

{
  "over_time":[
    { "actor": { "type":"project","id":1,"name":"Acme" },
      "data":[ { "date":"2025-02-01","value":42.8 }, ... ] }
  ],
  "current":[
    { "actor": { "type":"project","id":1,"name":"Acme" }, "share":48.12 },
    { "actor": { "type":"competitor","id":5,"name":"Contoso" }, "share":33.27 },
    { "actor": { "type":"competitor","id":7,"name":"Fabrikam" }, "share":18.61 }
  ],
  "breakdown": [
    { "rank":1, "actor": { "type":"project","id":1,"name":"Acme" }, "share":48.12 },
    { "rank":2, "actor": { "type":"competitor","id":5,"name":"Contoso" }, "share":33.27 },
    { "rank":3, "actor": { "type":"competitor","id":7,"name":"Fabrikam" }, "share":18.61 },
    { "rank":5, "actor": { "name":"Others" }, "share":12.00, "others":true }
  ],
  "others": [
    { "rank":5, "actor": { "type":"competitor","id":9,"name":"Globex" }, "share":7.00 }
  ]
}

Request

curl -X GET -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.llmpulse.ai/api/v1/metrics/top_sources?project_id=PROJECT_ID&range=30"

const response = await fetch("https://api.llmpulse.ai/api/v1/metrics/top_sources?project_id=PROJECT_ID&range=30", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.llmpulse.ai/api/v1/metrics/top_sources?project_id=PROJECT_ID&range=30",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

require 'httparty'

response = HTTParty.get(
  "https://api.llmpulse.ai/api/v1/metrics/top_sources?project_id=PROJECT_ID&range=30",
  headers: { "Authorization" => "Bearer YOUR_API_KEY" }
)
data = response.parsed_response

req, _ := http.NewRequest("GET", "https://api.llmpulse.ai/api/v1/metrics/top_sources?project_id=PROJECT_ID&range=30", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.llmpulse.ai/api/v1/metrics/top_sources?project_id=PROJECT_ID&range=30', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/metrics/top_sources?project_id=PROJECT_ID&range=30"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Response

{
  "project_id":"...",
  "from":"2025-02-01T00:00:00Z",
  "to":"2025-03-02T23:59:59Z",
  "filters":{ ... },
  "sort":"avg_mention_rate",
  "page":1,
  "per_page":20,
  "total":57,
  "data":[
    { "domain":"example.com", "total_responses":42, "avg_visibility":18.75, "avg_mention_rate":18.75 },
    { "domain":"another.com", "total_responses":37, "avg_visibility":15.10, "avg_mention_rate":15.10 }
  ],
  "request_id":"..."
}

Métricas

GET/metrics/timeseries

GET/metrics/summary

GET/metrics/prompt_summary

GET/metrics/sov

GET/metrics/top_sources

GET`/metrics/timeseries`

GET`/metrics/summary`

GET`/metrics/prompt_summary`

GET`/metrics/sov`

GET`/metrics/top_sources`