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

# List Experiments

> Lists experiments given a set of filters incl. their high-level statistics.

<RequestExample>
  ```python python theme={null}
  p = Parea(api_key="PAREA_API_KEY")  # replace with your API key

  exp_uuids = p.list_experiment_uuids(ListExperimentUUIDsFilters())
  ```

  ```typescript typescript theme={null}
  const p = new Parea("PAREA_API_KEY"); // replace with your API key

  const uuids = await p.listExperimentUUIDS();
  ```

  ```bash curl theme={null}
  curl --location 'https://parea-ai-backend-us-9ac16cdbc7a7b006.onporter.run/api/parea/v1/experiments' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: PAREA_API_KEY' \
  --data '{
      "experiment_name_filter": "Hello World",
      "metadata_filter": {
          "purpose": "testing"
      },
      "project_name": "development",
      "run_name_filter": "v1"
  }'
  ```
</RequestExample>


## OpenAPI

````yaml post /api/parea/v1/experiments
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /api/parea/v1/experiments:
    post:
      summary: List Experiments Api
      description: >-
        Lists experiments given a set of filters incl. their high-level
        statistics.
      operationId: list_experiments_api_api_parea_v1_experiments_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListExperimentsRequestSchema'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ExperimentWithStatsSchema'
                type: array
                title: Response List Experiments Api Api Parea V1 Experiments Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
        - APIKeyHeader: []
        - APIKeyHeader: []
components:
  schemas:
    ListExperimentsRequestSchema:
      properties:
        project_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Project Name
          description: Name of the project to filter experiments by.
        metadata_filter:
          anyOf:
            - type: object
            - type: 'null'
          title: Metadata Filter
          description: >-
            Filters experiments to contain the given metadata. The
            metadata_filter is a dictionary where the keys are the metadata keys
            and the values are the metadata values to filter by.
        experiment_name_filter:
          anyOf:
            - type: string
            - type: 'null'
          title: Experiment Name Filter
          description: Filters experiments to contain the given string in their name.
        run_name_filter:
          anyOf:
            - type: string
            - type: 'null'
          title: Run Name Filter
          description: Filters experiments to contain the given string in their run name.
        experiment_uuids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Experiment Uuids
          description: Filters experiments to contain the given UUIDs.
      type: object
      title: ListExperimentsRequestSchema
      examples:
        - experiment_name_filter: Hello World
          metadata_filter:
            purpose: testing
          project_name: development
          run_name_filter: v1
    ExperimentWithStatsSchema:
      properties:
        name:
          type: string
          title: Name
          description: Name of the experiment
        run_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Run Name
          description: >-
            Name of the run. Must be unique for each experiment and can only
            contain alphanumeric characters, hyphens, and underscores.
        project_uuid:
          type: string
          title: Project Uuid
          description: UUID of the project associated with this experiment
        is_public:
          type: boolean
          title: Is Public
          description: If experiment should be public
          default: false
        metadata:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Metadata
          description: >-
            Any additional key-value pairs which provide context or are useful
            for filtering.
        uuid:
          type: string
          title: Uuid
          description: UUID of the created experiment
        created_at:
          type: string
          title: Created At
          description: Timestamp the experiment was created
        status:
          allOf:
            - $ref: '#/components/schemas/ExperimentStatus'
          description: Status of the experiment
        pinned_stats:
          items:
            $ref: '#/components/schemas/ExperimentPinnedStatistic'
          type: array
          title: Pinned Stats
          description: >-
            List of population/dataset-level statistics. Typically contains mean
            of any reported scores, latencies, etc.
        num_samples:
          anyOf:
            - type: integer
            - type: 'null'
          title: Num Samples
          description: Number of samples in the experiment
      type: object
      required:
        - name
        - project_uuid
        - uuid
        - created_at
        - status
        - pinned_stats
      title: ExperimentWithStatsSchema
      examples:
        - created_at: '2024-04-15 22:19:13'
          is_public: false
          metadata:
            dataset: dev 123
          name: greeting
          num_samples: 6
          pinned_stats:
            - operation: mean
              value: 0.176471
              var1: levenshtein
            - operation: mean
              value: 0.00002
              var1: Cost
            - operation: mean
              value: 11
              var1: Total Tokens
            - operation: mean
              value: 9
              var1: Output Tokens
            - operation: mean
              value: 2
              var1: Input Tokens
            - operation: mean
              value: 0.65273
              var1: Latency
          project_uuid: ...
          run_name: bijou-kail
          status: completed
          uuid: ...
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ExperimentStatus:
      type: string
      enum:
        - pending
        - running
        - completed
        - failed
      title: ExperimentStatus
    ExperimentPinnedStatistic:
      properties:
        var1:
          type: string
          title: Var1
          description: Name of the first variable
        var2:
          anyOf:
            - type: string
            - type: 'null'
          title: Var2
          description: Name of the second variable
        operation:
          allOf:
            - $ref: '#/components/schemas/StatisticOperation'
          description: What operation was executed on the variables to get value
        value:
          type: number
          title: Value
          description: Value of the statistic
      type: object
      required:
        - var1
        - operation
        - value
      title: ExperimentPinnedStatistic
      examples:
        - operation: mean
          value: 0.23
          var1: Latency
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    StatisticOperation:
      type: string
      enum:
        - mean
        - median
        - variance
        - standard_deviation
        - min
        - max
        - mse
        - mae
        - correlation
        - spearman_correlation
        - accuracy
        - custom
      title: StatisticOperation
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-user-id

````