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

# Listar eventos

> Lo que los webhooks bancarios y de conexión avisaron, consultable. Más nuevos primero. Retención 400 días.

Todo lo que los webhooks bancarios y de conexión avisaron, consultable. Un
webhook que falló, o que nunca configuraste, no te deja sin saber qué pasó:
cada evento queda registrado con el mismo `data` que viaja en el webhook.

```bash theme={null}
curl "https://api.tupana.ai/v2/events/?type=movement.created&since=2026-10-28T00:00:00Z" \
  -H "Authorization: Api-Key TU_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "evnt_8102938475612001",
      "type": "movement.created",
      "api_version": 2,
      "created_at": "2026-10-28T09:12:04Z",
      "company_id": "ment_3672486436546233854",
      "resource_type": "bank_account",
      "resource_id": "bacc_7Hk2938475610293",
      "data": {
        "account_id": "bacc_7Hk2938475610293",
        "connection_id": "cred_9Pq5028174639201",
        "company_id": "ment_3672486436546233854",
        "movement_ids": ["move_Qm8102938475612"],
        "count": 1
      }
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 1, "total_pages": 1 },
  "links": { "next": null, "prev": null }
}
```

## Filtros

| Parámetro | Qué hace |
| - | - |
| `type` | Un evento bancario (`bank_account.refreshed`, `movement.created`, `bank_account.refresh_failed`, `connection.degraded`) o de conexión (`connection.active`, `connection.requires_action`). |
| `resource_id` | Los eventos de ese recurso (`bacc_…`, `cred_…`). |
| `since`, `until` | Rango de `created_at`, ISO 8601. |

Más nuevos primero. Se conservan 400 días. Una key sandbox ve solo los eventos
del [dataset sandbox](https://docs.tupana.ai/api-reference/v2/banking/guides/sandbox.md); una de
producción, solo los reales.


## OpenAPI

````yaml api-reference/openapi-v2.json GET /events/
openapi: 3.0.0
info:
  title: Tupana API — v2
  description: >-
    API v2 de Tupana: facturación electrónica, cesiones, recaudación, consultas,
    boleta de honorarios y nómina. Los identificadores de recursos son public
    IDs opacos con prefijo (docu_, ment_, cred_, doce_, empl_…).
  version: 2.0.0
servers:
  - url: https://api.tupana.ai/v2
    description: Producción (v2)
security:
  - apiKeyAuth: []
paths:
  /events/:
    get:
      tags:
        - Eventos
      summary: Listar eventos
      description: >-
        Lo que los webhooks bancarios y de conexión avisaron, consultable. Más
        nuevos primero. Retención 400 días.
      operationId: listEvents_v2
      parameters:
        - name: type
          in: query
          required: false
          schema:
            type: string
        - name: resource_id
          in: query
          required: false
          schema:
            type: string
        - name: since
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: until
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            default: 50
            maximum: 200
      responses:
        '200':
          description: Eventos
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiEvent'
                  meta:
                    type: object
                    properties:
                      page:
                        type: integer
                      page_size:
                        type: integer
                      total:
                        type: integer
                      total_pages:
                        type: integer
                  links:
                    type: object
                    properties:
                      next:
                        type: string
                        nullable: true
                      prev:
                        type: string
                        nullable: true
        '400':
          description: Filtro inválido (`parameter_invalid`)
        '403':
          description: >-
            La API key no tiene `banking:read` explícito (`code:
            banking_permission_required`)
      security:
        - apiKeyAuth: []
components:
  schemas:
    ApiEvent:
      type: object
      properties:
        id:
          type: string
          example: evnt_8102938475612001
        type:
          type: string
          enum:
            - bank_account.refreshed
            - bank_account.refresh_failed
            - movement.created
            - movement.updated
            - connection.degraded
            - connection.active
            - connection.requires_action
        api_version:
          type: integer
          example: 2
        created_at:
          type: string
          format: date-time
        company_id:
          type: string
          example: ment_3672486436546233854
        resource_type:
          type: string
          example: bank_account
        resource_id:
          type: string
          example: bacc_7Hk2938475610293
        data:
          type: object
          description: El mismo `data` del webhook.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API Key para autenticación. Debe proporcionarse en el header
        Authorization con el formato: 'Api-Key YOUR-API-KEY' (incluye el prefijo
        'Api-Key ' seguido de tu API key)

````

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