# list\_experiments

List experiments, optionally filtered by project, state, type, or metric.

List experiments, optionally filtered by project, state, type, or metric.

## Permissions

```json
{
  "ability": "mcp:read or mcp:write",
  "role": "Team membership and applicable entity view policies are required.",
  "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.",
  "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant."
}
```

## Input

```json
{
  "properties": {
    "project_id": {
      "description": "Optional project ID filter",
      "type": "integer"
    },
    "state_id": {
      "description": "Optional experiment state ID filter",
      "type": "integer"
    },
    "state": {
      "description": "Optional experiment state name filter",
      "type": "string"
    },
    "type": {
      "description": "Optional experiment type filter",
      "type": "string"
    },
    "metric_id": {
      "description": "Optional metric ID filter",
      "type": "integer"
    },
    "limit": {
      "description": "Result limit; defaults to 50 and is clamped to 1–100",
      "type": "integer"
    }
  },
  "type": "object"
}
```

## Output

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "project_id": {
            "type": [
              "integer",
              "null"
            ]
          },
          "name": {
            "type": "string"
          },
          "state_id": {
            "type": [
              "integer",
              "null"
            ]
          },
          "primary_metric_id": {
            "type": [
              "integer",
              "null"
            ]
          },
          "type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "ab_test",
              "multivariate_test",
              null
            ]
          },
          "result": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "conclusive_winner",
              "conclusive_loser",
              "inconclusive",
              "error",
              "other",
              null
            ]
          },
          "decision": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "implement",
              "rollout",
              "retest",
              "iterate",
              "reject",
              null
            ]
          },
          "start_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "end_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "project_id",
          "name",
          "state_id",
          "primary_metric_id",
          "type",
          "result",
          "decision",
          "start_date",
          "end_date",
          "created_at",
          "updated_at"
        ]
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      },
      "required": [
        "limit"
      ]
    }
  },
  "required": [
    "data",
    "meta"
  ]
}
```

## Examples

### Request arguments

```json
{
  "limit": 10
}
```

### Result

```json
{
  "data": [
    {
      "id": 101,
      "project_id": 1,
      "state_id": null,
      "primary_metric_id": null,
      "name": "Show delivery estimate",
      "type": "ab_test",
      "result": null,
      "decision": null,
      "start_date": null,
      "end_date": null,
      "created_at": "2026-01-15T12:00:00+00:00",
      "updated_at": "2026-01-15T12:00:00+00:00"
    }
  ],
  "meta": {
    "limit": 10
  }
}
```

## Errors

```json
[
  {
    "status": 401,
    "description": "Missing, expired, or revoked bearer token."
  },
  {
    "status": 403,
    "description": "Missing MCP ability, team membership, plan entitlement, or user permission."
  },
  {
    "status": 404,
    "description": "The MCP server is disabled."
  },
  {
    "status": 429,
    "description": "Rate limited; honor Retry-After before retrying."
  },
  {
    "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call."
  }
]
```

An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication).