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

# List environments

> Returns the scoped project's environments, optionally filtered by slug and disabled state. The run worker uses this to resolve env vars by slug.



## OpenAPI

````yaml /api-reference/openapi.generated.json get /api/environments/list
openapi: 3.1.0
info:
  title: Empirical API
  version: 1.0.0
  description: Programmatic access to Empirical test runs, snoozes, and more.
  contact:
    name: Empirical
    url: https://empirical.run
servers:
  - url: https://api.empirical.run
security:
  - Bearer: []
tags:
  - name: Test Runs
    description: Trigger, list, and inspect end-to-end test runs.
  - name: Test Cases
    description: >-
      Browse the Playwright test cases synced from a project's repository and
      manage their tags.
  - name: Environments
    description: >-
      Named deployment targets (slug + Playwright project filters) a project's
      tests run against.
  - name: Snoozes
    description: Temporarily suppress known test failures for specific Playwright tests.
  - name: KV
    description: >-
      Project-scoped key-value store shared by test runs, shards and agent
      sessions. Every entry expires; conditional writes make it safe for locks.
  - name: Analytics
    description: Aggregated test-run, test-count and test-case analytics for a project.
  - name: Badges
    description: Public README status badge images (SVG) for project environments.
  - name: Files
    description: >-
      Upload files of any type and get a link to use in tasks, sessions and
      messages. Agents should use the `upload_file` tool, which returns a
      project-wide `file@<id>` handle (`<id>` is the file `id` below).
  - name: Infra
    description: >-
      Infrastructure details customers configure against, such as static egress
      IPs.
  - name: Reporter Configuration
    description: Reporters a project can use in environment and run reporter configs.
paths:
  /api/environments/list:
    get:
      tags:
        - Environments
      summary: List environments
      description: >-
        Returns the scoped project's environments, optionally filtered by slug
        and disabled state. The run worker uses this to resolve env vars by
        slug.
      operationId: listEnvironments
      parameters:
        - schema:
            type: string
            description: When set to the string `false`, exclude disabled environments.
          required: false
          description: When set to the string `false`, exclude disabled environments.
          name: is_disabled
          in: query
        - schema:
            type: string
            minLength: 1
            description: Filter to the environment with this slug.
          required: false
          description: Filter to the environment with this slug.
          name: environment_slug
          in: query
      responses:
        '200':
          description: The project's environments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEnvironmentsResponse'
        '400':
          description: Invalid request or missing project scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Project not found or not accessible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ListEnvironmentsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            environments:
              type: array
              items:
                $ref: '#/components/schemas/Environment'
          required:
            - environments
          description: Response payload.
      required:
        - data
    ErrorResponse:
      type: object
      properties:
        data:
          nullable: true
          description: Always null for error responses.
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error message.
          required:
            - message
          description: Error details.
      required:
        - data
        - error
    Environment:
      type: object
      properties:
        id:
          type: number
          description: Unique identifier.
        project_id:
          type: number
          description: Project identifier.
        slug:
          type: string
          description: URL-friendly identifier.
        name:
          type: string
          description: Display name.
        playwright_projects_match:
          type: array
          items:
            type: string
          description: Playwright project names to match.
        playwright_projects_ignore:
          type: array
          items:
            type: string
          description: Playwright project names to ignore.
        is_disabled:
          type: boolean
          nullable: true
          description: Whether the environment is disabled.
        env_files:
          type: array
          items:
            type: string
          description: Environment file paths.
        scheduled_trigger:
          type: string
          nullable: true
          description: Cron expression for scheduled triggers.
        scheduled_concurrency:
          type: object
          nullable: true
          properties:
            group:
              type: string
              description: Concurrency group key.
            on_conflict:
              type: string
              enum:
                - cancel
                - wait
              description: Policy toward an active run in the group.
          required:
            - group
            - on_conflict
          description: >-
            Concurrency group and policy scheduled runs are triggered with; null
            uses the project's legacy concurrency setting.
        reporter_config:
          type: object
          properties:
            schema_version:
              type: number
              enum:
                - 1
              description: Reporter config schema version. Always `1`.
            reporters:
              type: array
              items:
                oneOf:
                  - type: object
                    properties:
                      reporter_type:
                        type: string
                        enum:
                          - slack_run_status
                        description: Posts run status updates to Slack channels.
                      slack_channel_ids:
                        type: array
                        items:
                          type: integer
                          minimum: 1
                        minItems: 1
                        description: >-
                          Registered Slack channel ids from `GET
                          /api/v2/slack/channels` (the numeric `id`, not the
                          Slack `C…` channel id). Must belong to the project's
                          organization and not be archived. Deduplicated and
                          sorted on save.
                    required:
                      - reporter_type
                      - slack_channel_ids
                    additionalProperties: false
                  - type: object
                    properties:
                      reporter_type:
                        type: string
                        enum:
                          - github_check
                        description: >-
                          Posts a GitHub check run on the build commit. Needs
                          `build` with a repository the GitHub Reporter app is
                          installed on.
                    required:
                      - reporter_type
                    additionalProperties: false
                  - type: object
                    properties:
                      reporter_type:
                        type: string
                        enum:
                          - github_pr_comment
                        description: >-
                          Posts (and updates) a comment on the pull request for
                          the build branch. Needs `build` with a repository the
                          GitHub Reporter app is installed on.
                    required:
                      - reporter_type
                    additionalProperties: false
                  - type: object
                    properties:
                      reporter_type:
                        type: string
                        enum:
                          - github_linked_changes
                        description: >-
                          Tracks the test branch named after the head branch of
                          the app pull request the run was triggered for
                          (`trigger.event` `pull_request`), and keeps the
                          `Empirical linked test changes` check on that pull
                          request up to date: it passes when the test branch has
                          nothing left to merge and fails while it has unmerged
                          commits. The pull request's latest run decides whether
                          it is tracked. Does nothing for runs not triggered by
                          a pull request. Needs `build` with a repository the
                          GitHub Reporter app is installed on.
                    required:
                      - reporter_type
                    additionalProperties: false
                  - type: object
                    properties:
                      reporter_type:
                        type: string
                        enum:
                          - email_run_report
                        description: >-
                          Emails a report when the run ends to every user whose
                          email domain is one of the organization's email
                          domains.
                    required:
                      - reporter_type
                    additionalProperties: false
              description: >-
                Reporters, at most one per `reporter_type`. Replaces the stored
                list on write; an empty array disables them.
          required:
            - schema_version
            - reporters
          additionalProperties: false
          description: Reporter configuration for runs in this environment.
        created_at:
          type: string
          nullable: true
          description: ISO 8601 timestamp.
        updated_at:
          type: string
          nullable: true
          description: ISO 8601 timestamp.
      required:
        - id
        - project_id
        - slug
        - name
        - playwright_projects_match
        - playwright_projects_ignore
        - is_disabled
        - env_files
        - scheduled_trigger
        - scheduled_concurrency
        - reporter_config
        - created_at
        - updated_at
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.