> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Listagem de Sincronizações Bancárias: O Que Cada Sincronização Fez

> O endpoint List Sync Runs da Didit retorna as sincronizações de uma conexão, com o gatilho, o status e os horários.

O endpoint de listagem de execuções de sincronização da Didit retorna as sincronizações de uma conexão, com o respectivo gatilho, status e horários.
Use-o para ver se uma sincronização foi `initial`, `scheduled` ou `requested`, e se ela foi bem-sucedida.
Para ver os detalhes de uma delas, consulte [Consultar uma execução de sincronização](https://docs.didit.me/pt-br/standalone-apis/bank-sync-run-get.md).


## OpenAPI

````yaml pt-br/openapi-25.json GET /v3/bank/connections/{id}/sync-runs/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de verificação de identidade. Autentique-se com o cabeçalho x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      Bank Link, conexões, contas, saldos, transações, instituições e cobertura.
      Os dados bancários estão disponíveis para aplicações do sandbox. As
      chamadas de uma aplicação em produção respondem `404` até que o acesso em
      produção seja anunciado. Nada é cobrado no sandbox. Uma chamada feita com
      chave de API exige uma chave que tenha a permissão de dados bancários
      (`bank-data`): leitura para consultas e escrita para operações que alteram
      algo. A verificação de conta é a exceção: ela exige acesso de escrita a
      sessões, ou acesso total, e não a permissão de dados bancários.


      Os dados bancários não fazem parte do acesso total: uma chave com acesso
      total é recusada, e a chamada responde `403 bank_data_access_denied` até
      que você crie uma chave que tenha a permissão. Os dados brutos do banco
      (contas, saldos, transações e o feed de alterações) também recusam uma
      requisição sem chave de API.


      Toda recusa em `/v3/bank/`, exceto a da verificação de conta, tem o mesmo
      corpo JSON (`code`, `message`, `request_id`, `field`, `next_action`,
      `retry_after`). Um caminho que não é uma operação, um ID que não é um UUID
      ou um subrecurso desconhecido responde `404 not_found` para todos os
      métodos, e qualquer erro inesperado responde `500 internal_error` com um
      `request_id`. Quando os dados bancários não estão disponíveis, toda
      operação responde o `404` padrão da plataforma, exatamente como ocorre com
      uma rota desconhecida.
paths:
  /v3/bank/connections/{id}/sync-runs/:
    get:
      tags:
        - Bank Data
      summary: Listar sincronizações
      description: >-
        Lista o que cada sincronização de uma conexão fez, das mais recentes
        para as mais antigas, por conta e por recurso.


        Requer uma chave de API com a permissão Dados bancários (`bank-data`):
        leitura para esta operação. Uma chave com acesso total não inclui essa
        permissão: conceda-a explicitamente ao criar a chave, ou a chamada
        responderá `403 bank_data_access_denied`.
      operationId: listBankSyncRuns
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: O ID da conexão.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
          description: 'Tamanho da página, de 1 a 500. Padrão: 100.'
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Cursor opaco de `next_cursor` da página anterior.
      responses:
        '200':
          description: Uma página de execuções de sincronização.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankSyncRunList'
              examples:
                Page:
                  summary: Uma execução
                  value:
                    items:
                      - id: d4a9e7b2-1c58-4f03-96ab-5e2d8c7f0b14
                        connection_id: 5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35
                        trigger: scheduled
                        status: succeeded
                        started_at: '2026-11-21T06:00:02Z'
                        finished_at: '2026-11-21T06:00:19Z'
                        results:
                          - account_id: a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                            resource: transactions
                            outcome: succeeded
                            added: 3
                            modified: 0
                            removed: 1
                            error: null
                          - account_id: a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                            resource: balances
                            outcome: succeeded
                            added: 0
                            modified: 0
                            removed: 0
                            error: null
                          - account_id: c3d84e19-2a7b-4f60-b5e1-9a0c6d3f8e72
                            resource: transactions
                            outcome: succeeded
                            added: 0
                            modified: 0
                            removed: 0
                            error: null
                        error: null
                    next_cursor: null
        '400':
          description: Um parâmetro é inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Invalid cursor:
                  summary: Cursor inválido
                  value:
                    code: invalid_cursor
                    message: The cursor or page token is not valid.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: cursor
                    next_action: null
                    retry_after: null
                Invalid request:
                  summary: Requisição inválida
                  value:
                    code: invalid_request
                    message: The request is not valid.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: limit
                    next_action: null
                    retry_after: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BankDataAccessDenied'
        '404':
          description: O recurso não existe nesta aplicação e neste ambiente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: Não encontrado
                  value:
                    code: not_found
                    message: The resource does not exist.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: null
                    retry_after: null
        '409':
          description: >-
            A conexão não está ativa: foi excluída, ou seu período de retenção
            terminou (`connection_not_active`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not active:
                  summary: Conexão não ativa
                  value:
                    code: connection_not_active
                    message: This connection is not active.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: create_link
                    retry_after: null
        '429':
          $ref: '#/components/responses/RateLimitedRead'
        '500':
          $ref: '#/components/responses/BankDataInternalError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            curl
            'https://verification.didit.me/v3/bank/connections/5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35/sync-runs/'
            \
              -H 'x-api-key: YOUR_API_KEY'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.bank.list_sync_runs(
                "11111111-2222-3333-4444-555555555555",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: >-
            import Didit from "@didit-protocol/sdk-node";


            // Reads DIDIT_API_KEY.

            const didit = new Didit();


            const result = await
            didit.bank.listSyncRuns("11111111-2222-3333-4444-555555555555");

            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.ListSyncRuns(ctx, \"11111111-2222-3333-4444-555555555555\", didit.BankListSyncRunsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.bank().listSyncRuns("11111111-2222-3333-4444-555555555555");

            System.out.println(result);
        - lang: php
          label: PHP
          source: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            $result =
            $didit->bank->listSyncRuns('11111111-2222-3333-4444-555555555555');

            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: >-
            require "didit"


            # Reads DIDIT_API_KEY.

            didit = Didit::Client.new


            result =
            didit.bank.list_sync_runs("11111111-2222-3333-4444-555555555555")

            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await
            client.Bank.ListSyncRunsAsync("11111111-2222-3333-4444-555555555555");

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    BankSyncRunList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BankSyncRun'
        next_cursor:
          type: string
          nullable: true
      required:
        - items
        - next_cursor
    BankDataError:
      type: object
      description: >-
        Corpo de erro de toda operação de Dados bancários. Todos os campos estão
        sempre presentes.
      properties:
        code:
          type: string
          enum:
            - ongoing_access_not_available
            - segment_not_available
            - window_not_available
            - history_window_ambiguous
            - redirect_url_not_registered
            - link_origin_not_allowed
            - bank_data_access_denied
            - connection_not_active
            - consent_expired
            - renewal_not_needed
            - renewal_window_expired
            - access_removed
            - refresh_limit_reached
            - cursor_expired
            - page_expired
            - invalid_cursor
            - page_token_mismatch
            - contract_rate_missing
            - insufficient_credits
            - invalid_request
            - not_found
            - internal_error
          description: >-
            Código de erro legível por máquina. Decida o fluxo com base neste
            valor, nunca em `message`.
        message:
          type: string
          description: >-
            Explicação em linguagem simples para o desenvolvedor. O texto pode
            mudar; não o processe.
        request_id:
          type: string
          description: >-
            Identificador desta requisição. Informe-o ao entrar em contato com o
            suporte.
        field:
          type: string
          description: >-
            O campo da requisição a ser corrigido, quando o erro se refere a um
            único campo. Caso contrário, `null`.
          nullable: true
        next_action:
          type: string
          enum:
            - retry_later
            - renew_connection
            - create_link
            - restart_from_cursor
            - restart_read
            - top_up_balance
            - enable_bank_data_access
            - contact_support
            - null
          description: >-
            O que fazer em seguida, para que um cliente possa agir sem
            adivinhar. `null` quando não há uma próxima etapa padrão.
          nullable: true
        retry_after:
          type: integer
          description: >-
            Segundos a aguardar antes de tentar novamente. Definido em erros de
            limite de requisições e erros temporários; caso contrário, `null`.
          nullable: true
      required:
        - code
        - message
        - request_id
        - field
        - next_action
        - retry_after
      example:
        code: ongoing_access_not_available
        message: >-
          This bank cannot keep access open. Use access one_time or choose
          another bank.
        request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
        field: institution_id
        next_action: create_link
        retry_after: null
    BankSyncRun:
      type: object
      description: >-
        Uma sincronização de uma conexão. Somente sincronizações iniciais,
        agendadas e solicitadas são listadas.
      properties:
        id:
          type: string
          format: uuid
        connection_id:
          type: string
          format: uuid
        trigger:
          type: string
          enum:
            - initial
            - scheduled
            - requested
        status:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - partial
            - failed
        started_at:
          type: string
          format: date-time
          nullable: true
        finished_at:
          type: string
          format: date-time
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/BankSyncRunResult'
          description: O que a execução fez, por conta e por recurso.
        error:
          type: object
          nullable: true
          description: >-
            Por que a execução falhou como um todo. `null` quando não falhou. Os
            erros de contas e recursos individuais estão em `results`.
          properties:
            code:
              type: string
            message:
              type: string
            at:
              type: string
              format: date-time
          required:
            - code
            - message
            - at
      required:
        - id
        - connection_id
        - trigger
        - status
        - started_at
        - finished_at
        - results
        - error
    RateLimitBudgetError:
      type: object
      description: >-
        Retornado somente em uma recusa de orçamento de limite de requisições do
        middleware. Outros erros 429, incluindo conflitos de idempotência e
        limites específicos de endpoint, não garantem esses campos de metadados.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: Mensagem de recusa por orçamento já existente, legível por humanos.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: >-
            Referência de suporte opaca: RL- seguido de 32 caracteres
            hexadecimais minúsculos de um UUID.
        limit:
          type: integer
          description: Orçamento do escopo excedido; igual a X-RateLimit-Limit.
        remaining:
          type: integer
          minimum: 0
          description: Orçamento restante, limitado a zero; igual a X-RateLimit-Remaining.
        reset:
          type: integer
          format: int64
          description: >-
            Horário de redefinição da janela em segundos Unix; é igual a
            X-RateLimit-Reset.
        window_seconds:
          type: integer
          description: >-
            Duração da janela fixa em segundos, não o tempo restante de espera.
            Respeite Retry-After antes de tentar novamente.
      example:
        detail: >-
          Write request rate limit exceeded. You can make up to 300 requests per
          minute.
        reference: RL-00000000000040008000000000000001
        limit: 300
        remaining: 0
        reset: 1794358860
        window_seconds: 60
    BankSyncRunResult:
      type: object
      properties:
        account_id:
          type: string
          description: '`null` para um resultado de toda a conexão.'
          format: uuid
          nullable: true
        resource:
          type: string
          enum:
            - accounts
            - balances
            - transactions
        outcome:
          type: string
          enum:
            - succeeded
            - failed
            - skipped
        added:
          type: integer
        modified:
          type: integer
        removed:
          type: integer
        error:
          allOf:
            - $ref: '#/components/schemas/BankSyncError'
          nullable: true
          description: Obrigatório quando `outcome` for `failed`.
      required:
        - account_id
        - resource
        - outcome
        - added
        - modified
        - removed
        - error
    BankSyncError:
      type: object
      description: Por que a sincronização falhou.
      properties:
        code:
          type: string
          description: Código de erro da Didit.
        message:
          type: string
          description: Explicação em linguagem simples.
        at:
          type: string
          description: Quando aconteceu. `null` em um resultado por conta.
          format: date-time
          nullable: true
      required:
        - code
        - message
        - at
  responses:
    Unauthorized:
      description: Não autorizado
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: Chave de API inválida
              value:
                detail: Invalid API Key.
    BankDataAccessDenied:
      description: >-
        A chave de API não tem a permissão Dados bancários (`bank-data`) ou,
        para dados brutos do banco em uma aplicação em produção, a configuração
        da aplicação "Bank data in the API" está desativada. Dados bancários não
        fazem parte do acesso total: uma chave com acesso total, uma chave
        restrita a outros recursos e uma requisição autenticada sem chave de API
        (credenciais de cliente, para dados brutos) são todas recusadas com este
        corpo, então crie uma chave e conceda a permissão explicitamente. A
        recusa acontece antes de qualquer busca, então ela não informa se um
        objeto existe.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Bank data not allowed:
              summary: Dados bancários não permitidos
              value:
                code: bank_data_access_denied
                message: >-
                  Bank data calls need an API key that carries the Bank data
                  permission.
                request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                field: null
                next_action: enable_bank_data_access
                retry_after: null
    RateLimitedRead:
      description: >-
        Limite de leitura do middleware excedido. Respeite o Retry-After antes
        de tentar novamente.
      headers:
        Retry-After:
          $ref: '#/components/headers/BudgetRetryAfter'
        X-RateLimit-Scope:
          $ref: '#/components/headers/BudgetXRateLimitScope'
        X-RateLimit-Limit:
          $ref: '#/components/headers/BudgetXRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/BudgetXRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/BudgetXRateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitBudgetError'
          example:
            detail: >-
              GET request rate limit exceeded. You can make up to 600 requests
              per minute.
            reference: RL-00000000000040008000000000000001
            limit: 600
            remaining: 0
            reset: 1794358860
            window_seconds: 60
    BankDataInternalError:
      description: >-
        Algo deu errado do lado da Didit. Qualquer erro inesperado em
        `/v3/bank/` responde no formato de erro Bank, nunca com uma página HTML:
        informe o `request_id` ao suporte.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: Um erro inesperado
              value:
                code: internal_error
                message: >-
                  Something went wrong on our side. Quote the request_id to
                  support.
                request_id: 3f6a1c8e92b54d07a1e38c4b7f0d2e59
                field: null
                next_action: contact_support
                retry_after: null
  headers:
    BudgetRetryAfter:
      description: >-
        Segundos a aguardar, arredondados para cima até a próxima janela.
        Presente nas recusas de orçamento do middleware.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: >-
        O escopo cujo orçamento foi excedido. Presente nas recusas de orçamento
        do middleware.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: >-
        Orçamento do escopo excedido; igual ao limite do corpo. Presente nas
        recusas de orçamento do middleware.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: >-
        Orçamento restante, limitado a zero; igual a remaining no corpo.
        Presente nas recusas de orçamento do middleware.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: >-
        Horário da redefinição em segundos Unix; igual à redefinição no corpo.
        Presente nas recusas de orçamento do middleware.
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        A chave de API da sua aplicação, obtida em Developers -> API keys no
        Business Console. A chave principal tem acesso completo. Uma chave
        nomeada pode ter escopo limitado: nenhum, leitura ou escrita por
        recurso, restrita a alguns fluxos ou a sessões aprovadas, a uma lista de
        endereços e a uma data de validade. 401 significa que a chave está
        incorreta, revogada ou expirada; 403 significa que nenhuma chave foi
        enviada, que a chave não tem acesso a este recurso ou ação, ou que a
        requisição partiu de um endereço fora da lista de endereços da chave;
        404 em uma rota de sessão significa que a sessão está fora dos fluxos ou
        status permitidos para a chave. Uma chave sem acesso a mídia recebe as
        URLs de imagem, vídeo e PDF como null, e uma chave sem escrita de
        sessões recebe os links e tokens de sessão como null. Veja
        https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.