> ## 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 agents > Same shape as `GET /api/v1/agents`, paid per call via x402. ## OpenAPI ````yaml https://playground.sanfoundation.com/openapi.yaml get /x402/v1/agents 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: get: tags: - x402 summary: List agents description: Same shape as `GET /api/v1/agents`, paid per call via x402. operationId: listAgentsX402 parameters: - $ref: '#/components/parameters/SearchQuery' - $ref: '#/components/parameters/AgentsLimit' responses: '200': $ref: '#/components/responses/AgentsList' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' security: - X402Payment: [] components: parameters: SearchQuery: in: query name: search required: false description: Case-insensitive substring filter on name, domain, and description. schema: type: string examples: byTopic: value: cyber byName: value: Noah AgentsLimit: in: query name: limit required: false description: Max number of agents to return. schema: type: integer minimum: 1 maximum: 500 default: 100 responses: AgentsList: description: OK — agent catalog. content: application/json: schema: $ref: '#/components/schemas/AgentsListResponse' 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 schemas: AgentsListResponse: type: object required: - count - agents properties: count: type: integer agents: type: array items: $ref: '#/components/schemas/AgentSummary' 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. 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. ````