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

# Get agent events

> Returns structured tool invocation and inference events for a running agent. Container events (shell, filesystem, runtime) come from the JSONL event log. Inference events (model_usage) are merged from the database with owner scoping. With follow=true, returns an SSE stream with initial inference backfill and 3-second polling for new inference rows alongside real-time container events. Without follow, returns a merged JSON array sorted by (timestamp, id). Scoped to ownership — users see own agents and own inference rows only.




## OpenAPI

````yaml /openapi.yaml get /agents/{id}/events
openapi: 3.0.3
info:
  title: Hill90 API
  description: Hill90 platform API — agent management and lifecycle operations.
  version: 0.1.0
servers:
  - url: /
    description: Relative (behind Traefik reverse proxy)
security: []
paths:
  /agents/{id}/events:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get agent events
      description: >
        Returns structured tool invocation and inference events for a running
        agent. Container events (shell, filesystem, runtime) come from the JSONL
        event log. Inference events (model_usage) are merged from the database
        with owner scoping. With follow=true, returns an SSE stream with initial
        inference backfill and 3-second polling for new inference rows alongside
        real-time container events. Without follow, returns a merged JSON array
        sorted by (timestamp, id). Scoped to ownership — users see own agents
        and own inference rows only.
      parameters:
        - name: tail
          in: query
          schema:
            type: integer
            default: 100
          description: Number of tail events
        - name: follow
          in: query
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: If "true", stream events via SSE
      responses:
        '200':
          description: Event output (JSON array or SSE stream)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentEvent'
            text/event-stream:
              schema:
                type: string
        '401':
          description: Not authenticated
        '403':
          description: Requires user role
        '404':
          description: Agent not found
        '409':
          description: Agent is not running
      security:
        - bearerAuth: []
components:
  schemas:
    AgentEvent:
      type: object
      properties:
        id:
          type: string
          description: >
            Event ID. Container events use UUID format. Inference events use
            "inference-<uuid>" prefix to avoid collision with container event
            IDs.
        timestamp:
          type: string
          format: date-time
        type:
          type: string
          enum:
            - command_start
            - command_complete
            - file_read
            - file_write
            - directory_list
            - identity_read
            - health_check
            - inference_complete
            - inference_error
            - inference_rate_limited
            - inference_budget_exceeded
            - inference_client_disconnect
          description: >
            Event type. Container events use command_start/complete, file_*,
            etc. Inference events use inference_complete for success, or
            inference_<status> for non-success statuses (error, rate_limited,
            budget_exceeded, client_disconnect).
        tool:
          type: string
          enum:
            - shell
            - filesystem
            - runtime
            - identity
            - health
            - inference
          description: |
            Tool category. Inference events always have tool=inference.
        input_summary:
          type: string
          description: >
            Truncated human-readable input (max 200 chars). For inference
            events, formatted as "model_name (request_type)".
        output_summary:
          type: string
          nullable: true
          description: >
            Metadata-only result summary. For container events: exit codes, byte
            counts. For inference events: "input_tokens+output_tokens tokens,
            $cost, latency_ms". Never contains raw output or prompt/completion
            content.
        duration_ms:
          type: integer
          nullable: true
        success:
          type: boolean
          nullable: true
        metadata:
          type: object
          nullable: true
          description: >
            Additional structured data. For inference events, contains:
            model_name (string), request_type (string), status (string),
            input_tokens (integer), output_tokens (integer), cost_usd (number).
            No prompt or completion content is included.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````