Consultar status de processamento de requisição

Use este endpoint para verificar se a Braze concluiu o processamento de um grupo de requisições assíncronas do endpoint /users/track.

Importante

Este endpoint está em beta. Se você tiver interesse em participar do beta, entre em contato com o gerente da sua conta Braze.

Uma resposta bem-sucedida de /users/track significa que a Braze recebeu sua requisição e a colocou na fila para processamento. Para confirmar que o processamento foi concluído, inclua o mesmo group_id em cada requisição /users/track relacionada e, em seguida, chame este endpoint com esse group_id. Quando o status do grupo for completed, você pode realizar com segurança ações que dependem desses dados, como disparar um Canvas ou lançar uma Campaign.

Para saber mais sobre o fluxo de trabalho completo, requisitos de ID de grupo, limites e retenção, consulte Rastrear status de processamento de requisição.

Pré-requisitos

Para usar este endpoint, você precisará de uma chave de API com a permissão users.track.status. A permissão users.track não inclui acesso a este endpoint.

Qualquer chave de API no espaço de trabalho com a permissão users.track.status pode consultar qualquer grupo nesse espaço de trabalho, independentemente de qual chave de API enviou as requisições /users/track.

Limite de frequência

A Braze aplica um limite de frequência de 1.500 solicitações por minuto por espaço de trabalho a esse endpoint, conforme documentado em Limites de frequência da API. Esse limite é separado do limite de frequência do /users/track.

Respostas bem-sucedidas incluem os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset para que você possa monitorar quanto da sua janela atual ainda está disponível.

Parâmetros de consulta

Exemplo de requisição

1
2

curl --location --request GET 'https://rest.iad-01.braze.com/users/track/status?group_id=loyalty_backfill_2026-09-23' \
--header 'Authorization: Bearer YOUR_REST_API_KEY'

Resposta

1
2
3
4
5
6
7
8
9
10
11
12

{
  "results": [
    {
      "group_id": (string) the group ID from your request,
      "status": (string) the processing status of the group, either "processing" or "completed",
      "received": (integer) the number of /users/track requests Braze accepted for this group,
      "done": (integer) the number of accepted requests Braze has finished processing,
      "processing": (integer) the number of accepted requests Braze is still processing,
      "final_completion_time": (string or null) when the last request in the group finished processing, in ISO 8601 format (UTC). This is null until the status is "completed".
    }
  ]
}

O array results contém um objeto quando a Braze encontra o grupo. Ele fica vazio quando o grupo não existe no espaço de trabalho ou quando o período de retenção de 24 horas expirou. A Braze retorna um array results vazio em ambos os casos, portanto um array vazio não indica se um grupo já existiu.

Parâmetros de resposta

Um status completed significa que a Braze concluiu o processamento de todas as requisições do grupo, incluindo requisições em que a Braze rejeitou alguns objetos. Este endpoint informa apenas contagens de requisições e não reporta resultados para atributos, eventos ou compras individuais. Para encontrar objetos rejeitados, verifique o array errors em cada resposta de /users/track.

Exemplos de resposta

Grupo ainda em processamento

1
2
3
4
5
6
7
8
9
10
11
12

{
  "results": [
    {
      "group_id": "loyalty_backfill_2026-09-23",
      "status": "processing",
      "received": 4,
      "done": 3,
      "processing": 1,
      "final_completion_time": null
    }
  ]
}

Grupo concluído

1
2
3
4
5
6
7
8
9
10
11
12

{
  "results": [
    {
      "group_id": "loyalty_backfill_2026-09-23",
      "status": "completed",
      "received": 4,
      "done": 4,
      "processing": 0,
      "final_completion_time": "2026-09-23T18:58:57.123Z"
    }
  ]
}

Grupo não encontrado ou expirado

1
2
3

{
  "results": []
}

Solução de problemas

A tabela a seguir lista os erros que este endpoint pode retornar e como resolvê-los.

Para outros códigos de status e mensagens de erro, consulte Erros fatais e respostas.