> ## 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 Jornadas

> Lista as jornadas do container: cada item traz o lead e os eventos dele em ordem cronológica. Aceita os mesmos filtros de [Listar leads](/api-reference/listar-leads).

Como cada item carrega os eventos, o `limit` máximo é 50.


## Exemplo

```bash
curl "https://api.metrito.com/v3/tracking/journeys?created_after=2026-11-01&limit=20" \
  -H "Authorization: Bearer mtk_live_..."
```


## OpenAPI

````yaml /openapi/tracking.yaml get /v3/tracking/journeys
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/journeys:
    get:
      summary: Listar jornadas
      description: >
        Lista as jornadas do container: cada item traz o lead e os eventos dele
        em ordem cronológica. Aceita os mesmos filtros de [Listar
        leads](/api-reference/listar-leads).


        Como cada item carrega os eventos, o `limit` máximo é 50.
      operationId: listJourneys
      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: Jornadas por página (1 a 50).
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 50
        - name: events_limit
          in: query
          description: Máximo de eventos por jornada, a partir do primeiro (1 a 500).
          schema:
            type: integer
            default: 200
            minimum: 1
            maximum: 500
      responses:
        '200':
          description: Página de jornadas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JourneyListResponse'
        '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:
    JourneyListResponse:
      type: object
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Journey'
        page:
          type: integer
        limit:
          type: integer
        has_more:
          type: boolean
    Journey:
      type: object
      properties:
        object:
          type: string
          const: journey
        lead:
          $ref: '#/components/schemas/Lead'
        events_count:
          type: integer
        first_event_at:
          type:
            - string
            - 'null'
          format: date-time
        last_event_at:
          type:
            - string
            - 'null'
          format: date-time
        events:
          type: array
          items:
            $ref: '#/components/schemas/JourneyEvent'
    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
    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
    JourneyEvent:
      type: object
      properties:
        object:
          type: string
          const: event
        id:
          type: string
        event_id:
          type:
            - string
            - 'null'
          description: ID usado na deduplicação com a Meta.
        name:
          type: string
          example: PageView
        time:
          type: string
          format: date-time
        source:
          type: string
          description: De onde o evento veio.
          example: website
        url:
          type:
            - string
            - 'null'
        referrer:
          type:
            - string
            - 'null'
        utm:
          type: object
          additionalProperties: true
        data:
          type: object
          description: Dados enviados com o evento (valor, moeda, produto etc.).
          additionalProperties: true
        whatsapp_connection:
          type:
            - object
            - 'null'
          description: Número de WhatsApp que atendeu, em eventos de WhatsApp.
          properties:
            id:
              type:
                - string
                - 'null'
            name:
              type:
                - string
                - 'null'
            phone:
              type:
                - string
                - 'null'
  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.