Endpoints de analytics e métricas

API · v1 · Homologação · Revisado em 2026-10-19 · Markdown

Estas 7 operações estão em homologação em https://api.staging.agilink.io/v1. Exemplos usam recursos fictícios. A referência interativa contém os schemas completos de cada campo, inclusive objetos internos. Leia também o guia da integração e a migração de tokens.

Todas as requisições usam Authorization: Bearer <credencial>. Sessão humana e chave limitada são indicadas por operação. OAuth depende da Tarefa 2. Estas consultas são somente de leitura e não exigem Idempotency-Key nem If-Match. Nunca envie credenciais em query strings.

GET /analytics/summary

Totais e indicadores por período/filtros.

Permissão: analytics:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	query	sim	AppId
`start`	query	sim	AnalyticsInstant
`end`	query	sim	AnalyticsInstant
`timezone`	query	não	string
`group`	query	não	—
`linkId`	query	não	LinkId
`domain`	query	não	Domain
`prefix`	query	não	string
`campaignId`	query	não	string
`folderId`	query	não	string
`tagId`	query	não	string
`device`	query	não	—
`source`	query	não	string
`country`	query	não	string

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/analytics/summary?appId=app_loja&start=2026-10-01T00%3A00%3A00Z&end=2026-10-02T00%3A00%3A00Z' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
`X-Request-Id`	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
`Cache-Control`	Respostas administrativas não podem ser armazenadas.	no-store, no-transform

{
  "data": {
    "appId": "app_loja",
    "period": {
      "start": "2026-10-01T00:00:00Z",
      "end": "2026-10-02T00:00:00Z",
      "timezone": "America/Sao_Paulo",
      "startInclusive": true,
      "endExclusive": true
    },
    "filters": {
      "campaignId": null,
      "folderId": null,
      "tagId": null,
      "group": "all",
      "linkId": null,
      "domain": null,
      "prefix": null,
      "device": null,
      "source": null,
      "country": null,
      "eventType": "all"
    },
    "generatedAt": "2026-10-02T12:00:00Z",
    "coverage": {
      "source": "event_rows",
      "grouping": "current_link_group",
      "deletedLinks": "excluded",
      "historicalAggregates": "not_merged",
      "uniqueVisitors": "distinct_click_hash_estimate",
      "nativeTrust": "client_reported",
      "completenessGuaranteed": false,
      "limitations": [
        "Totais calculados das linhas disponíveis; agregados históricos não são somados.",
        "Abertura não comprova instalação."
      ]
    },
    "totals": {
      "clicks": 3,
      "uniqueVisitors": 1,
      "identifiedClicks": 2,
      "appOpens": 2,
      "contentViews": 1,
      "legacyContentLoads": 0,
      "activeLinks": 1,
      "firstEventAt": "2026-10-01T01:00:00Z",
      "lastEventAt": "2026-10-01T02:00:00Z"
    }
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

GET /analytics/timeseries

Série com granularidade suportada.

Permissão: analytics:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	query	sim	AppId
`start`	query	sim	AnalyticsInstant
`end`	query	sim	AnalyticsInstant
`timezone`	query	não	string
`group`	query	não	—
`linkId`	query	não	LinkId
`domain`	query	não	Domain
`prefix`	query	não	string
`campaignId`	query	não	string
`folderId`	query	não	string
`tagId`	query	não	string
`device`	query	não	—
`source`	query	não	string
`country`	query	não	string
`granularity`	query	não	—

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/analytics/timeseries?appId=app_loja&start=2026-10-01T00%3A00%3A00Z&end=2026-10-02T00%3A00%3A00Z' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
`X-Request-Id`	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
`Cache-Control`	Respostas administrativas não podem ser armazenadas.	no-store, no-transform

{
  "data": {
    "appId": "app_loja",
    "period": {
      "start": "2026-10-01T00:00:00Z",
      "end": "2026-10-02T00:00:00Z",
      "timezone": "America/Sao_Paulo",
      "startInclusive": true,
      "endExclusive": true
    },
    "filters": {
      "campaignId": null,
      "folderId": null,
      "tagId": null,
      "group": "all",
      "linkId": null,
      "domain": null,
      "prefix": null,
      "device": null,
      "source": null,
      "country": null,
      "eventType": "all"
    },
    "generatedAt": "2026-10-02T12:00:00Z",
    "coverage": {
      "source": "event_rows",
      "grouping": "current_link_group",
      "deletedLinks": "excluded",
      "historicalAggregates": "not_merged",
      "uniqueVisitors": "distinct_click_hash_estimate",
      "nativeTrust": "client_reported",
      "completenessGuaranteed": false,
      "limitations": [
        "Totais calculados das linhas disponíveis; agregados históricos não são somados.",
        "Abertura não comprova instalação."
      ]
    },
    "granularity": "day",
    "sparse": true,
    "buckets": [
      {
        "start": "2026-09-30T03:00:00Z",
        "localLabel": "2026-09-30T00:00",
        "clicks": 3,
        "uniqueVisitors": 1,
        "identifiedClicks": 2,
        "appOpens": 2,
        "contentViews": 1,
        "legacyContentLoads": 0
      }
    ]
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

GET /analytics/breakdown

Dimensões disponíveis e valores agregados.

Permissão: analytics:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	query	sim	AppId
`start`	query	sim	AnalyticsInstant
`end`	query	sim	AnalyticsInstant
`timezone`	query	não	string
`group`	query	não	—
`linkId`	query	não	LinkId
`domain`	query	não	Domain
`prefix`	query	não	string
`campaignId`	query	não	string
`folderId`	query	não	string
`tagId`	query	não	string
`device`	query	não	—
`source`	query	não	string
`country`	query	não	string
`dimension`	query	sim	—
`eventType`	query	não	—
`limit`	query	não	integer

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/analytics/breakdown?appId=app_loja&start=2026-10-01T00%3A00%3A00Z&end=2026-10-02T00%3A00%3A00Z&dimension=device' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
`X-Request-Id`	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
`Cache-Control`	Respostas administrativas não podem ser armazenadas.	no-store, no-transform

{
  "data": {
    "appId": "app_loja",
    "period": {
      "start": "2026-10-01T00:00:00Z",
      "end": "2026-10-02T00:00:00Z",
      "timezone": "America/Sao_Paulo",
      "startInclusive": true,
      "endExclusive": true
    },
    "filters": {
      "campaignId": null,
      "folderId": null,
      "tagId": null,
      "group": "all",
      "linkId": null,
      "domain": null,
      "prefix": null,
      "device": null,
      "source": null,
      "country": null,
      "eventType": "all"
    },
    "generatedAt": "2026-10-02T12:00:00Z",
    "coverage": {
      "source": "event_rows",
      "grouping": "current_link_group",
      "deletedLinks": "excluded",
      "historicalAggregates": "not_merged",
      "uniqueVisitors": "distinct_click_hash_estimate",
      "nativeTrust": "client_reported",
      "completenessGuaranteed": false,
      "limitations": [
        "Totais calculados das linhas disponíveis; agregados históricos não são somados.",
        "Abertura não comprova instalação."
      ]
    },
    "dimension": "device",
    "truncated": false,
    "items": [
      {
        "value": "android",
        "events": 6,
        "clicks": 3,
        "uniqueVisitors": 1,
        "identifiedClicks": 2,
        "appOpens": 2,
        "contentViews": 1,
        "legacyContentLoads": 0
      }
    ]
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

GET /analytics/top-links

Ranking paginado.

Permissão: analytics:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	query	sim	AppId
`start`	query	sim	AnalyticsInstant
`end`	query	sim	AnalyticsInstant
`timezone`	query	não	string
`group`	query	não	—
`linkId`	query	não	LinkId
`domain`	query	não	Domain
`prefix`	query	não	string
`campaignId`	query	não	string
`folderId`	query	não	string
`tagId`	query	não	string
`device`	query	não	—
`source`	query	não	string
`country`	query	não	string
`limit`	query	não	integer
`cursor`	query	não	Cursor

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/analytics/top-links?appId=app_loja&start=2026-10-01T00%3A00%3A00Z&end=2026-10-02T00%3A00%3A00Z' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
`X-Request-Id`	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
`Cache-Control`	Respostas administrativas não podem ser armazenadas.	no-store, no-transform

{
  "data": {
    "appId": "app_loja",
    "period": {
      "start": "2026-10-01T00:00:00Z",
      "end": "2026-10-02T00:00:00Z",
      "timezone": "America/Sao_Paulo",
      "startInclusive": true,
      "endExclusive": true
    },
    "filters": {
      "campaignId": null,
      "folderId": null,
      "tagId": null,
      "group": "all",
      "linkId": null,
      "domain": null,
      "prefix": null,
      "device": null,
      "source": null,
      "country": null,
      "eventType": "all"
    },
    "generatedAt": "2026-10-02T12:00:00Z",
    "coverage": {
      "source": "event_rows",
      "grouping": "current_link_group",
      "deletedLinks": "excluded",
      "historicalAggregates": "not_merged",
      "uniqueVisitors": "distinct_click_hash_estimate",
      "nativeTrust": "client_reported",
      "completenessGuaranteed": false,
      "limitations": [
        "Totais calculados das linhas disponíveis; agregados históricos não são somados.",
        "Abertura não comprova instalação."
      ]
    },
    "items": [
      {
        "linkId": "go.example.com~-ofertas~-tenis",
        "title": "Tênis",
        "domain": "go.example.com",
        "prefix": "ofertas",
        "slug": "tenis",
        "clicks": 3,
        "uniqueVisitors": 1,
        "lastClickAt": "2026-10-01T02:00:00Z"
      }
    ]
  },
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

GET /analytics/events

Eventos individuais autorizados e paginados.

Permissão: analytics:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	query	sim	AppId
`start`	query	sim	AnalyticsInstant
`end`	query	sim	AnalyticsInstant
`timezone`	query	não	string
`group`	query	não	—
`linkId`	query	não	LinkId
`domain`	query	não	Domain
`prefix`	query	não	string
`campaignId`	query	não	string
`folderId`	query	não	string
`tagId`	query	não	string
`device`	query	não	—
`source`	query	não	string
`country`	query	não	string
`eventType`	query	não	—
`limit`	query	não	integer
`cursor`	query	não	Cursor

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/analytics/events?appId=app_loja&start=2026-10-01T00%3A00%3A00Z&end=2026-10-02T00%3A00%3A00Z' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
`X-Request-Id`	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
`Cache-Control`	Respostas administrativas não podem ser armazenadas.	no-store, no-transform

{
  "data": {
    "appId": "app_loja",
    "period": {
      "start": "2026-10-01T00:00:00Z",
      "end": "2026-10-02T00:00:00Z",
      "timezone": "America/Sao_Paulo",
      "startInclusive": true,
      "endExclusive": true
    },
    "filters": {
      "campaignId": null,
      "folderId": null,
      "tagId": null,
      "group": "all",
      "linkId": null,
      "domain": null,
      "prefix": null,
      "device": null,
      "source": null,
      "country": null,
      "eventType": "all"
    },
    "generatedAt": "2026-10-02T12:00:00Z",
    "coverage": {
      "source": "event_rows",
      "grouping": "current_link_group",
      "deletedLinks": "excluded",
      "historicalAggregates": "not_merged",
      "uniqueVisitors": "distinct_click_hash_estimate",
      "nativeTrust": "client_reported",
      "completenessGuaranteed": false,
      "limitations": [
        "Totais calculados das linhas disponíveis; agregados históricos não são somados.",
        "Abertura não comprova instalação."
      ]
    },
    "events": [
      {
        "id": "80000000-0000-4000-8000-000000000001",
        "appId": "app_loja",
        "linkId": "go.example.com~-ofertas~-tenis",
        "type": "click",
        "producer": "worker",
        "trust": "worker_observed",
        "occurredAt": "2026-10-01T01:00:00Z",
        "receivedAt": "2026-10-01T01:00:00Z",
        "device": "android",
        "source": "direct",
        "country": "BR",
        "entryMethod": "unknown",
        "openId": null,
        "parentEventId": null
      }
    ]
  },
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

GET /analytics/native

Aberturas, conteúdo e métricas nativas.

Permissão: analytics:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	query	sim	AppId
`start`	query	sim	AnalyticsInstant
`end`	query	sim	AnalyticsInstant
`timezone`	query	não	string
`group`	query	não	—
`linkId`	query	não	LinkId
`domain`	query	não	Domain
`prefix`	query	não	string
`campaignId`	query	não	string
`folderId`	query	não	string
`tagId`	query	não	string
`device`	query	não	—
`source`	query	não	string
`country`	query	não	string

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/analytics/native?appId=app_loja&start=2026-10-01T00%3A00%3A00Z&end=2026-10-02T00%3A00%3A00Z' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
`X-Request-Id`	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
`Cache-Control`	Respostas administrativas não podem ser armazenadas.	no-store, no-transform

{
  "data": {
    "appId": "app_loja",
    "period": {
      "start": "2026-10-01T00:00:00Z",
      "end": "2026-10-02T00:00:00Z",
      "timezone": "America/Sao_Paulo",
      "startInclusive": true,
      "endExclusive": true
    },
    "filters": {
      "campaignId": null,
      "folderId": null,
      "tagId": null,
      "group": "all",
      "linkId": null,
      "domain": null,
      "prefix": null,
      "device": null,
      "source": null,
      "country": null,
      "eventType": "all"
    },
    "generatedAt": "2026-10-02T12:00:00Z",
    "coverage": {
      "source": "event_rows",
      "grouping": "current_link_group",
      "deletedLinks": "excluded",
      "historicalAggregates": "not_merged",
      "uniqueVisitors": "distinct_click_hash_estimate",
      "nativeTrust": "client_reported",
      "completenessGuaranteed": false,
      "limitations": [
        "Totais calculados das linhas disponíveis; agregados históricos não são somados.",
        "Abertura não comprova instalação."
      ]
    },
    "appOpens": 2,
    "contentViews": 1,
    "legacyContentLoads": 0,
    "confirmedOpens24h": 1,
    "matureOpens24h": 2,
    "provisionalOpens24h": 0,
    "cohortWindowHours": 24,
    "contentViewRate24h": 0.5
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

GET /analytics/recovery

Etapas e cobertura das recuperações implementadas.

Permissão: analytics:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	query	sim	AppId
`start`	query	sim	AnalyticsInstant
`end`	query	sim	AnalyticsInstant
`timezone`	query	não	string
`group`	query	não	—
`linkId`	query	não	LinkId
`domain`	query	não	Domain
`prefix`	query	não	string

Sem corpo de requisição.

Exemplo completo de requisição (substitua os identificadores fictícios):

curl --request GET 'https://api.staging.agilink.io/v1/analytics/recovery?appId=app_loja&start=2026-10-01T00%3A00%3A00Z&end=2026-10-02T00%3A00%3A00Z' \
  --header 'Authorization: Bearer <credencial>'

Resposta: 200. Sucesso. Exemplo fictício.

Header	Significado	Exemplo
`X-Request-Id`	Identificador gerado pelo servidor, inclusive para falhas e replays.	—
`Cache-Control`	Respostas administrativas não podem ser armazenadas.	no-store, no-transform

{
  "data": {
    "appId": "app_loja",
    "period": {
      "start": "2026-10-01T00:00:00Z",
      "end": "2026-10-02T00:00:00Z",
      "timezone": "America/Sao_Paulo",
      "startInclusive": true,
      "endExclusive": true
    },
    "filters": {
      "campaignId": null,
      "folderId": null,
      "tagId": null,
      "group": "all",
      "linkId": null,
      "domain": null,
      "prefix": null,
      "device": null,
      "source": null,
      "country": null,
      "eventType": "all"
    },
    "generatedAt": "2026-10-02T12:00:00Z",
    "coverage": {
      "source": "retained_recovery_tokens",
      "grouping": "current_link_group",
      "deletedLinks": "excluded",
      "historicalAggregates": "not_merged",
      "uniqueVisitors": "distinct_click_hash_estimate",
      "nativeTrust": "client_reported",
      "completenessGuaranteed": false,
      "limitations": [
        "Totais calculados das linhas disponíveis; agregados históricos não são somados.",
        "Abertura não comprova instalação."
      ]
    },
    "issuedTokens": 1,
    "stages": [
      {
        "stage": "recovered",
        "eventCount": 1,
        "tokens": 1
      }
    ]
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.