> ## Documentation Index > Fetch the complete documentation index at: https://docs.sanfoundation.com/llms.txt > Use this file to discover all available pages before exploring further. # List events > Same shape as `GET /api/v1/agents/{ref}/events`, paid per call via x402. ## OpenAPI ````yaml https://playground.sanfoundation.com/openapi.yaml get /x402/v1/agents/{ref}/events openapi: 3.1.0 info: title: SAN Foundation Gateway API version: 1.0.0 description: | Public API for the SAN Foundation gateway. The same data is exposed through two interchangeable surfaces: `/api/v1/*` is authenticated with an `x-api-key` (`sk_…`) and billed in credits (per-call cost in `x-credits`); `/x402/v1/*` is paid per call in USDC over the [x402 protocol](https://x402.org) and requires no API key (per-call cost in `x-price-usd`). servers: - url: https://gateway.sanfoundation.com description: Production security: [] tags: - name: API Key description: | Operations under `/api/v1/*`. Authenticate with a SAN API key (`x-api-key` header) and pay with prepaid credits — see each operation's `x-credits` for the per-call cost. - name: x402 description: | Operations under `/x402/v1/*`. Pay per call in USDC over the [x402 protocol](https://x402.org) — see each operation's `x-price-usd` for the per-call cost. No API key required. - name: Registration description: | Public, unauthenticated self-onboarding for agents. One call mints an API key and grants the signup credit so an agent can immediately use `/api/v1/*`. Rate limited per client IP. paths: /x402/v1/agents/{ref}/events: get: tags: - x402 summary: List events description: Same shape as `GET /api/v1/agents/{ref}/events`, paid per call via x402. operationId: listAgentEventsX402 parameters: - $ref: '#/components/parameters/AgentRef' - $ref: '#/components/parameters/EventsLimit' responses: '200': $ref: '#/components/responses/AgentEvents' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '404': $ref: '#/components/responses/AgentNotFound' security: - X402Payment: [] components: parameters: AgentRef: in: path name: ref required: true description: | Flexible agent identifier. Accepts any of: * UUID — `488ed3ff-6a4d-42e5-8e24-44eeef77959c` * Name (case-insensitive) — `Noah`, `noah`, `NOAH` * Slug — lowercase name with spaces as underscores * External ID — `017`, `17`, `069`, `69` (`#` and zero-padding tolerated) schema: type: string examples: byName: value: Noah byExternalId: value: '017' byUuid: value: 488ed3ff-6a4d-42e5-8e24-44eeef77959c EventsLimit: in: query name: limit required: false description: Max number of events to return. schema: type: integer minimum: 1 maximum: 30 default: 10 responses: AgentEvents: description: OK — recent canonical events for the agent. content: application/json: schema: $ref: '#/components/schemas/AgentEventsResponse' BadRequest: description: | Malformed input — typically a `limit` outside the documented bounds for the route, an unknown agent `ref`, or a malformed `evt_…` id. On `/x402/v1/*`, these guards run **before** payment, so the client is not charged. content: application/json: schema: $ref: '#/components/schemas/Error' examples: limitOutOfRange: value: error: limit out of range min: 1 max: 30 agentNotFound: value: error: agent not found ref: unknown-handle badEventId: value: error: invalid event id shape eventId: not-an-evt PaymentRequired: description: | x402 payment challenge. The structured `PaymentRequired` payload is returned in the **`PAYMENT-REQUIRED`** response header as a base64-encoded JSON object — see [x402.org](https://x402.org) for the decoded shape (clients must accept either `x402Version: 1` or `x402Version: 2`). For non-browser clients, the response body is also a JSON `PaymentRequired` payload. Browser clients (those whose `Accept` header indicates `text/html`) instead receive a paywall HTML page in the body. headers: PAYMENT-REQUIRED: description: | Base64-encoded JSON `PaymentRequired` payload describing the x402 challenge the client must satisfy. See [x402.org](https://x402.org) for the decoded shape. schema: type: string AgentNotFound: description: No agent matched the supplied `ref`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: agent not found ref: unknown-handle schemas: AgentEventsResponse: type: object required: - agent - count - events properties: agent: $ref: '#/components/schemas/AgentSummary' count: type: integer events: type: array items: $ref: '#/components/schemas/PublicEvent' Error: type: object required: - error properties: error: type: string ref: type: string description: Echoed back when an agent ref could not be resolved. eventId: type: string description: Echoed back when an event id could not be resolved. min: type: integer description: Echoed back on a `limit out of range` error. max: type: integer description: Echoed back on a `limit out of range` error. AgentSummary: type: object required: - id - externalId - name - slug - domain - description properties: id: type: string format: uuid externalId: type: - string - 'null' description: Short human-readable code (e.g. "017"). name: type: string description: Display name / codename (e.g. "Noah"). slug: type: string description: Lowercase, underscore-separated form of the name. domain: type: string description: Broad subject area the agent monitors. description: type: string description: Free-text description of what the agent does and tracks. PublicEvent: type: object required: - eventId - title - summary - firstSeenAt - lastUpdatedAt - primaryAgent - eventType - status - confidence - tags - sourceCount - entities - locations - sources properties: eventId: type: string description: Stable canonical event identifier. title: type: string description: Canonical (deduplicated) headline. summary: type: string occurredAt: type: - string - 'null' format: date-time description: When the underlying event occurred, if known. firstSeenAt: type: string format: date-time lastUpdatedAt: type: string format: date-time primaryAgent: type: string description: Display name of the primary agent. eventType: type: string description: e.g. `statement`, `release`, `incident`. status: type: string description: e.g. `active`, `archived`. confidence: type: string enum: - low - medium - high tags: type: array items: type: string sourceCount: type: integer description: Number of distinct source articles clustered into this event. entities: type: array items: $ref: '#/components/schemas/EventEntity' locations: type: array items: $ref: '#/components/schemas/EventLocation' sources: type: array items: $ref: '#/components/schemas/EventSource' EventEntity: type: object required: - name - type - role properties: name: type: string type: type: string description: e.g. `person`, `organization`, `concept`. role: type: string description: e.g. `primary`, `mentioned`. EventLocation: type: object required: - name properties: name: type: string country: type: - string - 'null' EventSource: type: object required: - url properties: url: type: string format: uri publication: type: - string - 'null' publishedAt: type: - string - 'null' format: date-time securitySchemes: X402Payment: type: apiKey in: header name: Payment-Signature description: | Base64-encoded signed payment payload as defined by the [x402 protocol](https://x402.org). Omit on the first attempt to receive the `402` challenge in the `PAYMENT-REQUIRED` response header; include it on the retry to settle payment and receive the resource. The legacy header name `X-PAYMENT` is also accepted by the server for backward compatibility — clients may send either, but `Payment-Signature` is preferred. See [x402.org](https://x402.org) for the on-the-wire shape of the `PaymentRequired` challenge and the settlement receipt returned in the `PAYMENT-RESPONSE` response header. ````