> ## Documentation Index > Fetch the complete documentation index at: https://docs.metrito.com/llms.txt > Use this file to discover all available pages before exploring further. # Listar Leads > Lista os leads de um container, do mais recente para o mais antigo. Com uma chave de API **do container**, o container vem da própria chave e `container_id` é dispensável. Com uma chave **do workspace**, passe `container_id`. Por padrão só voltam leads **identificados** (com nome, e-mail, telefone ou documento). Os filtros `email`, `phone` e `document` buscam o lead exato: não é busca por trecho do texto. ## Buscar o lead pelo telefone (ex.: DataCrazy, n8n) O caso mais comum: chegou uma conversa no CRM e você quer saber de onde aquele lead veio. Busque pelo telefone em qualquer formato: com ou sem `+`, DDI, espaços, traços e com ou sem o nono dígito. O número é encontrado em todas essas formas. Número sem `+` e com 10 ou 11 dígitos é tratado como brasileiro sem DDI. ```bash curl "https://api.metrito.com/v3/tracking/leads?phone=5511999998888" \ -H "Authorization: Bearer mtk_live_..." ``` Pegue o `id` do lead retornado e chame [Jornada do lead](https://docs.metrito.com/api-reference/jornada-do-lead.md) para ver os eventos e as UTMs. ## Paginação Use `page` e `limit` (até 100). Continue enquanto `has_more` for `true`. ```bash curl "https://api.metrito.com/v3/tracking/leads?created_after=2026-11-01&limit=100&page=2" \ -H "Authorization: Bearer mtk_live_..." ``` ## OpenAPI ````yaml /openapi/tracking.yaml get /v3/tracking/leads openapi: 3.1.0 info: title: API de Rastreamento — Metrito version: '3.0' description: > API para envio de eventos de rastreamento, consulta de leads e jornadas, gerenciamento de gatilhos (triggers) e webhooks de transação. ## Conceitos - **Container** — O contêiner de rastreamento vinculado a um domínio. - **Gatilho (Trigger)** — Uma *configuração* que define quando e como uma conversão deve ser disparada (tipo de disparo, mapeamento Meta, condições). Recurso CRUD. - **Lead** — Uma pessoa rastreada no container (identificada por nome, e-mail, telefone ou documento). - **Jornada** — O lead com todos os eventos dele em ordem cronológica. - **Evento** — Um *dado de rastreamento* enviado em tempo real: "usuário visualizou página X", "usuário comprou Y". Transitório, processado via fila. ## Infraestrutura - Rate limiting via `X-RateLimit-*` headers - Request ID via `X-Request-Id` em todas as respostas - `Idempotency-Key` suportado em POSTs de criação e ingestão servers: - url: https://api.metrito.com description: Produção security: - bearerAuth: [] - apiKeyAuth: [] paths: /v3/tracking/leads: get: summary: Listar leads description: > Lista os leads de um container, do mais recente para o mais antigo. Com uma chave de API **do container**, o container vem da própria chave e `container_id` é dispensável. Com uma chave **do workspace**, passe `container_id`. Por padrão só voltam leads **identificados** (com nome, e-mail, telefone ou documento). Os filtros `email`, `phone` e `document` buscam o lead exato: não é busca por trecho do texto. operationId: listLeads parameters: - $ref: '#/components/parameters/ContainerIdQuery' - $ref: '#/components/parameters/LeadPhone' - $ref: '#/components/parameters/LeadEmail' - $ref: '#/components/parameters/LeadDocument' - $ref: '#/components/parameters/CreatedAfter' - $ref: '#/components/parameters/CreatedBefore' - $ref: '#/components/parameters/IdentifiedOnly' - $ref: '#/components/parameters/IncludeBots' - $ref: '#/components/parameters/Order' - $ref: '#/components/parameters/Page' - name: limit in: query description: Leads por página (1 a 100). schema: type: integer default: 50 minimum: 1 maximum: 100 responses: '200': description: Página de leads content: application/json: schema: $ref: '#/components/schemas/LeadListResponse' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' security: - bearerAuth: [] - apiKeyAuth: [] components: parameters: ContainerIdQuery: name: container_id in: query required: false description: > Container a consultar (ObjectId, domínio ou `MTC-XXXX`). Dispensável com chave de API do container; obrigatório com chave do workspace. schema: type: string example: MTC-AB12 LeadPhone: name: phone in: query description: >- Telefone do lead em qualquer formato. Acha o lead com ou sem DDI 55 e com ou sem o nono dígito. Com `+` na frente, o DDI é o que veio no número. schema: type: string example: '5511999998888' LeadEmail: name: email in: query description: E-mail do lead, sem diferenciar maiúsculas de minúsculas. schema: type: string example: cliente@email.com LeadDocument: name: document in: query description: CPF ou CNPJ, com ou sem pontuação. schema: type: string example: 123.456.789-00 CreatedAfter: name: created_after in: query description: Só leads criados a partir desta data (ISO 8601). schema: type: string format: date-time example: '2026-11-01T00:00:00-03:00' CreatedBefore: name: created_before in: query description: Só leads criados até esta data (ISO 8601). schema: type: string format: date-time IdentifiedOnly: name: identified_only in: query description: >- `true` (padrão) devolve só leads com nome, e-mail, telefone ou documento. `false` inclui visitantes anônimos. schema: type: boolean default: true IncludeBots: name: include_bots in: query description: > `true` (padrão) inclui leads que tiveram alguma visita de robô de revisão da Meta, igual à tela de Leads do app. A marcação vale para o lead inteiro, então um lead real pode estar marcado. Use `false` para tirar esses leads. schema: type: boolean default: true Order: name: order in: query description: Ordem pela data de criação. schema: type: string enum: - desc - asc default: desc Page: name: page in: query schema: type: integer default: 1 minimum: 1 schemas: LeadListResponse: type: object properties: object: type: string const: list data: type: array items: $ref: '#/components/schemas/Lead' page: type: integer limit: type: integer has_more: type: boolean Lead: type: object properties: object: type: string const: lead id: type: string description: Identificador do lead (o mesmo `mlid` usado no rastreamento). example: lead_20261113_jp77jfdh6t name: type: - string - 'null' email: type: - string - 'null' phone: type: - string - 'null' example: '+5511999998888' document: type: - string - 'null' gender: type: - string - 'null' birth_date: type: - string - 'null' format: date city: type: - string - 'null' state: type: - string - 'null' country: type: - string - 'null' last_utms: type: object description: Últimas UTMs vistas para o lead. additionalProperties: true example: utm_source: facebook utm_medium: cpc utm_campaign: black-friday first_referrer: type: - string - 'null' first_referrer_at: type: - string - 'null' format: date-time is_bot: type: boolean created_at: type: string format: date-time updated_at: type: - string - 'null' format: date-time ErrorResponse: type: object properties: error: type: object properties: type: type: string enum: - authentication_error - authorization_error - validation_error - rate_limit_error - not_found_error - api_error code: type: string message: type: string request_id: type: string nullable: true responses: ValidationError: description: Parâmetro ausente ou inválido content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: validation_error code: invalid_parameter message: trigger.type must be 'api' for Partner API triggers request_id: req_abc123 Unauthorized: description: API key ausente, inválida, revogada ou expirada content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: authentication_error code: invalid_api_key message: The API key provided is invalid or has been revoked. request_id: req_abc123 Forbidden: description: A chave não tem acesso a este container content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: authorization_error code: forbidden message: Container out of API key scope request_id: req_abc123 RateLimited: description: Rate limit excedido headers: Retry-After: schema: type: integer X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: rate_limit_error code: rate_limit_exceeded message: Rate limit exceeded. Maximum 120 requests per 60s. request_id: req_abc123 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT or API Key description: JWT da plataforma ou API key `mtk_live_...` apiKeyAuth: type: apiKey in: header name: x-api-key description: API key `mtk_live_...` via header `x-api-key` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.