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

> List S2 basins with prefix filtering and cursor-based pagination.

# List basins.

<Tip>
  Model paging by specifying `start_after` as the last basin name that was returned.
</Tip>


## OpenAPI

````yaml get /basins
openapi: 3.1.0
info:
  title: S2, the durable streams API
  description: Streams as a cloud storage primitive.
  termsOfService: https://s2.dev/terms
  contact:
    email: support@s2.dev
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://aws.s2.dev/v1
security:
  - access_token: []
tags:
  - name: metrics
    description: Usage metrics and data.
  - name: basins
    description: Manage basins
  - name: access-tokens
    description: Manage access tokens
  - name: locations
    description: Manage locations
  - name: streams
    description: Manage streams
  - name: records
    description: Manage records
paths:
  /basins:
    get:
      tags:
        - basins
      summary: List basins.
      operationId: list_basins
      parameters:
        - name: prefix
          in: query
          description: Filter to basins whose names begin with this prefix.
          required: false
          schema:
            type: string
            default: ''
        - name: start_after
          in: query
          description: >-
            Filter to basins whose names lexicographically start after this
            string.
          required: false
          schema:
            type: string
            default: ''
        - name: limit
          in: query
          description: Number of results, up to a maximum of 1000.
          required: false
          schema:
            type: integer
            default: 1000
            maximum: 1000
            minimum: 0
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBasinsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '408':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
components:
  schemas:
    ListBasinsResponse:
      type: object
      required:
        - basins
        - has_more
      properties:
        basins:
          type: array
          items:
            $ref: '#/components/schemas/BasinInfo'
          description: Matching basins.
          maxItems: 1000
        has_more:
          type: boolean
          description: Indicates that there are more basins that match the criteria.
    ErrorInfo:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
    BasinInfo:
      type: object
      required:
        - name
        - created_at
      properties:
        created_at:
          type: string
          format: date-time
          description: Creation time in RFC 3339 format.
        deleted_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Deletion time in RFC 3339 format, if the basin is being deleted.
        location:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/LocationName'
              description: Basin location.
        name:
          $ref: '#/components/schemas/BasinNameStr'
          description: Basin name.
    LocationName:
      type: string
      maxLength: 64
      minLength: 1
    BasinNameStr:
      type: string
      maxLength: 48
      minLength: 8
  securitySchemes:
    access_token:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your access token.

````