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

# Get an event

> Get one venue event by ID.

`id` is the event UUID from [List events](/api-reference/perps-api/actions/list-events) or [Get activity](/api-reference/perps-api/actions/get-activity). Events outside the calling project return `404`.


## OpenAPI

````yaml openapi-perps.json GET /v1/events/{id}
openapi: 3.0.0
info:
  title: 'Yield API: Trade (Perps)'
  description: >-
    API Documentation. Errors follow a uniform envelope with `details.code` from
    the public catalog (https://docs.yield.xyz). ValidationPipe failures use
    `validation.message: string[]`.
  version: '1.0'
  contact: {}
servers:
  - url: https://perps.yield.xyz
    description: Production
security: []
tags:
  - name: Discovery
    description: Browse and discover perps markets, networks, and providers
  - name: Portfolio
    description: User-specific positions, orders, and balances
  - name: Actions
    description: Generate transactions to open, close, and manage positions
externalDocs:
  description: For more information
  url: https://docs.yield.xyz
paths:
  /v1/events/{id}:
    get:
      tags:
        - Events
        - Actions
      summary: Get event by ID
      description: Retrieve a single perp event by its UUID.
      operationId: EventsController_getEvent_v1
      parameters:
        - name: id
          required: true
          in: path
          description: The unique identifier of the event (UUID)
          schema:
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
            type: string
      responses:
        '200':
          description: Event details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventDto'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 401
                  timestamp:
                    type: string
                    example: '2026-05-04T12:00:00.000Z'
                  path:
                    type: string
                    example: /v1/actions
                  message:
                    type: string
                    example: Invalid API key
                  details:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Invalid API key
                      code:
                        type: string
                        example: AUTH_INVALID_API_KEY
        '404':
          description: Event not found with the specified ID
        '429':
          description: Rate limit exceeded
          headers:
            x-ratelimit-limit:
              description: Request limit per window
              schema:
                type: string
            x-ratelimit-remaining:
              description: Remaining requests (will be 0)
              schema:
                type: string
            x-ratelimit-reset:
              description: Unix timestamp when window resets
              schema:
                type: string
            retry-after:
              description: Seconds to wait before retrying
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 429
                  timestamp:
                    type: string
                    example: '2026-05-04T12:00:00.000Z'
                  path:
                    type: string
                    example: /v1/actions
                  message:
                    type: string
                    example: Rate limit exceeded
                  details:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Rate limit exceeded
                      code:
                        type: string
                        example: RATE_LIMIT_EXCEEDED
                      error:
                        type: string
                        example: Too Many Requests
                      retryAfter:
                        type: number
                        example: 30
      security:
        - ApiKey: []
components:
  schemas:
    EventDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        eventType:
          allOf:
            - $ref: '#/components/schemas/PerpEventType'
        providerId:
          type: string
          example: hyperliquid
        occurredAt:
          type: string
          format: date-time
        marketId:
          type: string
          nullable: true
        perpActionId:
          type: string
          nullable: true
          format: uuid
          description: Linked action; null for liquidations
        providerOrderId:
          type: string
          nullable: true
          description: Venue order identifier (e.g. Hyperliquid oid)
        explorerUrl:
          type: string
          nullable: true
          description: Block explorer URL for the settlement transaction
          example: >-
            https://app.hyperliquid.xyz/explorer/tx/0x8a3fb2c1d4e5f67890abcdef12345678901234567890abcdef1234567890abcd
        order:
          description: Normalized order details for the venue event
          allOf:
            - $ref: '#/components/schemas/EventOrderDto'
      required:
        - id
        - eventType
        - providerId
        - occurredAt
        - order
    PerpEventType:
      type: string
      enum:
        - order_filled
        - liquidation
        - stop_loss_triggered
        - take_profit_triggered
    EventOrderDto:
      type: object
      properties:
        orderId:
          type: string
          description: Venue order identifier (e.g. Hyperliquid oid)
          example: '394438950581'
        marketId:
          type: string
          description: Market identifier
          example: hyperliquid-eth-usdc
        asset:
          type: string
          description: Base asset ticker
          example: ETH
        side:
          description: Order side
          example: buy
          allOf:
            - $ref: '#/components/schemas/OrderSide'
        type:
          description: Normalized order type
          example: market
          allOf:
            - $ref: '#/components/schemas/OrderType'
        originalSizeBase:
          type: string
          description: Original order size in base asset units
          example: '0.0063'
        remainingSizeBase:
          type: string
          description: Remaining order size in base asset units
          example: '0.0'
        limitPrice:
          type: number
          description: Limit price
          example: 2395.2
        timeInForce:
          description: Normalized time in force
          example: ioc
          allOf:
            - $ref: '#/components/schemas/EventOrderTimeInForce'
        triggerPrice:
          type: number
          description: Trigger price when present on a trigger order
          example: 2500
        reduceOnly:
          type: boolean
          description: Reduce only flag
          example: false
        isPositionLevel:
          type: boolean
          description: Whether the order is a position-level TP/SL order
          example: false
        clientOrderId:
          type: object
          description: Client-supplied order id when present
          example: null
          nullable: true
        childOrderIds:
          description: Child order identifiers
          example: []
          type: array
          items:
            type: string
        createdAt:
          type: string
          description: Order creation timestamp
          format: date-time
          example: '2026-04-23T07:52:05.187Z'
        closedPnl:
          type: string
          description: >-
            PnL realized when an order closes, net of fees in USDC
            (string-encoded decimal). Absent on open / non-closing fills.
          example: '-12.45'
        fillPrice:
          type: number
          description: >-
            Realized fill price for fill-sourced events (e.g. order_filled,
            stop_loss_triggered). One per partial fill — aggregate across rows
            with the same orderId for an order-level average.
          example: 2500.5
      required:
        - orderId
        - marketId
        - asset
        - side
        - type
        - originalSizeBase
        - remainingSizeBase
        - reduceOnly
        - isPositionLevel
        - clientOrderId
        - childOrderIds
        - createdAt
    OrderSide:
      type: string
      enum:
        - buy
        - sell
      description: Order side
    OrderType:
      type: string
      enum:
        - market
        - limit
        - stop_loss
        - take_profit
      description: Order type
    EventOrderTimeInForce:
      type: string
      enum:
        - ioc
        - gtc
        - alo
      description: Normalized time in force
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key

````

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