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

# List saved lists

> List Pharen Hub saved lists the API key can read, with team, search, ordering, and pagination filters to discover list UUIDs before reading rows.

Returns saved lists the key creator can access. Use this endpoint before reading list rows, fields, views, or linked automation data.

<Note>
  Required API key scope: `lists:read`.
</Note>

## Query parameters

<ParamField query="team_id" type="string">
  Team UUID. Required for team-scoped keys and useful when you want to list one team's data.
</ParamField>

<ParamField query="ordering" type="string">
  Sort expression. Supported fields include `created_at`, `updated_at`, `name`, `field_count`, and `row_count`. Prefix with `-` for descending order.
</ParamField>

<ParamField query="page" type="integer">
  Page number for paginated responses.
</ParamField>

<ParamField query="page_size" type="integer">
  Number of lists per page.
</ParamField>

## Response

<ResponseField name="count" type="integer">
  Total number of matching lists.
</ResponseField>

<ResponseField name="next" type="string">
  URL for the next page, if one exists.
</ResponseField>

<ResponseField name="previous" type="string">
  URL for the previous page, if one exists.
</ResponseField>

<ResponseField name="results" type="array">
  List records visible to the key.
</ResponseField>


## OpenAPI

````yaml openapi.json GET /api/lists/
openapi: 3.1.0
info:
  title: Pharen Hub API
  version: 1.0.0
  description: >-
    Scoped REST API for Pharen Hub workspaces, calendars, lists, docs,
    workflows, and agents.
servers:
  - url: '{baseUrl}'
    description: Pharen Hub API base URL
    variables:
      baseUrl:
        default: https://pharen.app
        description: >-
          The Pharen Hub API origin. Keep the default for production, or enter
          another environment such as http://localhost:8000.
security:
  - bearerAuth: []
tags:
  - name: Calendar
    description: Calendar source and event operations.
  - name: Lists
    description: Saved list data and metadata operations.
  - name: Docs
    description: Document and collection operations.
  - name: Workflows
    description: Workflow definition and execution operations.
  - name: Agents
    description: Agent catalog and chat operations.
paths:
  /api/lists/:
    get:
      tags:
        - Lists
      summary: List saved lists
      description: >-
        Fetch list metadata and saved list data available to the API key.
        Requires the `lists:read` scope.
      operationId: listLists
      parameters:
        - name: team_id
          in: query
          description: Team UUID for team-scoped keys.
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          description: Page number for paginated results.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          description: Number of results per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Lists returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedLists'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    PaginatedLists:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/List'
        total:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
    List:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        team_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: forbidden
            message:
              type: string
              example: This API key does not have the required scope.
            details:
              type: object
              additionalProperties: true
  responses:
    Unauthorized:
      description: The request did not include a valid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        The API key is valid but does not have the required scope or workspace
        access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Paste your Pharen API key without the Bearer prefix.
      x-default: phk_your_api_key

````