> ## 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 reports > Same shape as `GET /api/v1/agents/{ref}/reports`, paid per call via x402. ## OpenAPI ````yaml https://playground.sanfoundation.com/openapi.yaml get /x402/v1/agents/{ref}/reports 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}/reports: get: tags: - x402 summary: List reports description: >- Same shape as `GET /api/v1/agents/{ref}/reports`, paid per call via x402. operationId: listAgentReportsX402 parameters: - $ref: '#/components/parameters/AgentRef' - $ref: '#/components/parameters/ReportsLimit' responses: '200': $ref: '#/components/responses/AgentReports' '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 ReportsLimit: in: query name: limit required: false description: Max number of reports to return. schema: type: integer minimum: 1 maximum: 3 default: 1 responses: AgentReports: description: OK — recent generated reports for the agent. content: application/json: schema: $ref: '#/components/schemas/AgentReportsResponse' 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: AgentReportsResponse: type: object required: - agent - count - reports properties: agent: $ref: '#/components/schemas/AgentSummary' count: type: integer reports: type: array items: $ref: '#/components/schemas/Report' 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. Report: type: object description: | A generated SAN intelligence report for an agent. The four audience lenses defined by the SAN brief — `personal`, `research`, `business_operations`, `trading_investments` — are surfaced through the `situation` and `decisionAdvantage` blocks keyed by lens name. required: - reportId - agentSlug - agentCodename - title - summary - analysis - coverageWindow - asOf - generatedAt - sourceEventIds - region - situation - decisionAdvantage - nextLikelyDevelopments - confidence properties: reportId: type: string agentSlug: type: string agentCodename: type: string title: type: string summary: type: string description: Short executive summary. analysis: type: string description: Long-form Markdown analysis. trend: type: - string - 'null' enum: - stable - developing - escalating - de-escalating - uncertain - null description: Direction of the situation since the prior report. coverageWindow: $ref: '#/components/schemas/CoverageWindow' asOf: type: string format: date-time generatedAt: type: string format: date-time generationReason: type: - string - 'null' triggerType: type: - string - 'null' description: e.g. `scheduled`, `manual`, `signal`. changeScore: type: - number - 'null' sourceEventIds: type: array description: | Canonical event ids that justify this report's claims. Each id can be resolved to its full event envelope via `GET /api/v1/events/{eventId}` or `GET /x402/v1/events/{eventId}`. items: type: string inboundSignalIds: type: array items: type: string region: type: array items: type: string situation: $ref: '#/components/schemas/Situation' decisionAdvantage: $ref: '#/components/schemas/DecisionAdvantageByLens' nextLikelyDevelopments: type: array items: type: string confidence: $ref: '#/components/schemas/Confidence' CoverageWindow: type: object required: - windowType - start - end properties: windowType: type: string description: e.g. `rolling_24h`, `rolling_7d`, `since_last`. start: type: - string - 'null' format: date-time end: type: - string - 'null' format: date-time Situation: type: object description: | Single narrative block describing the current state of the topic the agent monitors. Audience-specific framing lives on `decisionAdvantage`, not here. required: - headline - what_happened - what_changed - why_it_matters properties: headline: type: string description: One-line characterization of the current state. what_happened: type: string description: Concrete observed events behind this report. what_changed: type: string description: How the picture differs from the prior report. why_it_matters: type: string description: Stakes and implications. DecisionAdvantageByLens: type: object description: Per-audience decision-advantage payload, one block per lens. required: - personal - research - business_operations - trading_investments properties: personal: $ref: '#/components/schemas/DecisionAdvantageBlock' research: $ref: '#/components/schemas/DecisionAdvantageBlock' business_operations: $ref: '#/components/schemas/DecisionAdvantageBlock' trading_investments: $ref: '#/components/schemas/DecisionAdvantageBlock' Confidence: type: object required: - overall - notes properties: overall: type: string enum: - low - medium - high notes: type: array items: type: string DecisionAdvantageBlock: type: object description: Audience-specific take on what to do next. required: - bottom_line - recommended_posture - time_horizon properties: bottom_line: type: string description: Single sentence answer for "so what?". recommended_posture: type: string description: Suggested action or stance for this audience. time_horizon: type: string description: Short phrase such as `intraday`, `hours`, `days`, `weeks`. 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. ````