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

# List Events

> Returns paginated events for an app with optional filters.



## OpenAPI

````yaml GET /apps/{appId}/events
openapi: 3.1.0
info:
  title: Vela API
  description: Event ingestion, schema management, and notification rules for Vela.
  version: 1.0.0
  contact:
    name: Vela Support
    email: support@vela.dev
servers:
  - url: https://api.vela.dev/v1
    description: Production
  - url: http://localhost:3000/v1
    description: Local development
security:
  - clientSecret: []
paths:
  /apps/{appId}/events:
    get:
      tags:
        - Events
      summary: List Events
      description: Returns paginated events for an app with optional filters.
      operationId: list-events
      parameters:
        - $ref: '#/components/parameters/AppId'
        - name: level
          in: query
          description: Filter by level
          schema:
            type: string
            enum:
              - info
              - warning
              - error
              - success
        - name: type
          in: query
          description: Filter by event name
          schema:
            type: string
        - name: from
          in: query
          description: Start of time range (ISO-8601)
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: End of time range (ISO-8601)
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: Results per page (max 100)
          schema:
            type: integer
            default: 25
            maximum: 100
        - name: cursor
          in: query
          description: Pagination cursor from previous response
          schema:
            type: string
      responses:
        '200':
          description: Paginated events
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  nextCursor:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Cursor for the next page. `null` when there are no more
                      pages.
              example:
                items:
                  - id: evt-uuid
                    appId: app-uuid
                    event: payment.failed
                    customer_id: cust_42
                    data:
                      orderId: ord_1
                      reason: card_declined
                    level: error
                    metadata:
                      env: production
                    timestamp: '2024-06-01T12:00:00.000Z'
                    ingestedAt: '2024-06-01T12:00:00.123Z'
                nextCursor: eyJpZCI6ImV2dC11dWlkIn0=
      security:
        - clientSecret: []
components:
  parameters:
    AppId:
      name: appId
      in: path
      required: true
      description: App UUID or slug
      schema:
        type: string
      example: order-service
  schemas:
    Event:
      type: object
      properties:
        id:
          type: string
          description: Event identifier
        appId:
          type: string
          format: uuid
        event:
          type: string
          description: Event name
        customer_id:
          type:
            - string
            - 'null'
          description: Customer identifier
        data:
          type: object
          description: Event payload
        level:
          type: string
          enum:
            - info
            - warning
            - error
            - success
        metadata:
          type: object
          description: Contextual metadata
        timestamp:
          type: string
          format: date-time
        ingestedAt:
          type: string
          format: date-time
  securitySchemes:
    clientSecret:
      type: http
      scheme: bearer
      description: 'Client secret for management API access. Format: `vela_cs_...`'

````