# List metrics

GET /metrics. Parameters, permissions, request and response schemas.

`GET /metrics`

List metrics. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.

## Authentication

Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication).

```json
{
  "ability": "read",
  "team": "Token-bound Team",
  "authorization": "Additional role, entity-policy and plan requirements vary by operation."
}
```

## Parameters

| Name                        | Location | Required | Description                                                                                                                                  |
| --------------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `page[number]`              | query    | No       | Page number, starting at 1.                                                                                                                  |
| `page[size]`                | query    | No       | Results per page. Values above the configured maximum are capped.                                                                            |
| `sort`                      | query    | No       | Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, name, winning\_direction, type, project\_id.           |
| `filter[id]`                | query    | No       | Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.                 |
| `filter[project_id]`        | query    | No       | Filter by project\_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.        |
| `filter[name]`              | query    | No       | Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.               |
| `filter[winning_direction]` | query    | No       | Filter by winning\_direction. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters. |
| `filter[type]`              | query    | No       | Filter by type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.               |

### page\[number]

```json
{
  "type": "integer",
  "minimum": 1,
  "default": 1
}
```

### page\[size]

```json
{
  "type": "integer",
  "minimum": 1,
  "maximum": 30,
  "default": 30
}
```

### sort

```json
{
  "type": "string"
}
```

### filter\[id]

```json
{
  "type": "string"
}
```

### filter\[project\_id]

```json
{
  "type": "string"
}
```

### filter\[name]

```json
{
  "type": "string"
}
```

### filter\[winning\_direction]

```json
{
  "type": "string"
}
```

### filter\[type]

```json
{
  "type": "string"
}
```

## Example request

```bash
curl --request GET 'https://api.example.test/api/metrics' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json'
```

Examples use fictional data. Replace resource IDs and the API host with your environment’s values.

## Responses

### 200

Array of `MetricResource`

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "import_source": {
            "type": [
              "string",
              "null"
            ]
          },
          "import_source_ref": {
            "type": [
              "string",
              "null"
            ]
          },
          "import_source_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "data_import_id": {
            "type": [
              "integer",
              "null"
            ]
          },
          "imported_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "project_id": {
            "type": [
              "integer",
              "null"
            ]
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "average-per-user",
                  "rate-per-user",
                  "average-per-session",
                  "rate-per-session"
                ],
                "title": "MetricType"
              },
              {
                "type": "null"
              }
            ]
          },
          "winning_direction": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "increasing",
                  "decreasing"
                ],
                "title": "MetricWinningDirection"
              },
              {
                "type": "null"
              }
            ]
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_platform": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_synced_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "external_metadata": {
            "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.",
            "anyOf": [
              {
                "type": "object",
                "additionalProperties": {
                  "description": "An arbitrary JSON value retained by a metadata/settings field.",
                  "oneOf": [
                    {
                      "type": "null"
                    },
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/JsonValue"
                      }
                    },
                    {
                      "type": "object",
                      "additionalProperties": {
                        "$ref": "#/components/schemas/JsonValue"
                      }
                    }
                  ]
                }
              },
              {
                "type": "array",
                "items": {
                  "description": "An arbitrary JSON value retained by a metadata/settings field.",
                  "oneOf": [
                    {
                      "type": "null"
                    },
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "string"
                    },
                    {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/JsonValue"
                      }
                    },
                    {
                      "type": "object",
                      "additionalProperties": {
                        "$ref": "#/components/schemas/JsonValue"
                      }
                    }
                  ]
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "deleted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "import_source",
          "import_source_ref",
          "import_source_id",
          "data_import_id",
          "imported_at",
          "project_id",
          "name",
          "description",
          "type",
          "winning_direction",
          "external_id",
          "external_platform",
          "external_synced_at",
          "external_metadata",
          "created_at",
          "updated_at",
          "deleted_at"
        ],
        "title": "MetricResource"
      }
    },
    "links": {
      "type": "object",
      "properties": {
        "first": {
          "type": [
            "string",
            "null"
          ]
        },
        "last": {
          "type": [
            "string",
            "null"
          ]
        },
        "prev": {
          "type": [
            "string",
            "null"
          ]
        },
        "next": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "first",
        "last",
        "prev",
        "next"
      ]
    },
    "meta": {
      "type": "object",
      "properties": {
        "current_page": {
          "type": "integer",
          "minimum": 1
        },
        "from": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1
        },
        "last_page": {
          "type": "integer",
          "minimum": 1
        },
        "links": {
          "type": "array",
          "description": "Generated paginator links.",
          "items": {
            "type": "object",
            "properties": {
              "url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "label": {
                "type": "string"
              },
              "active": {
                "type": "boolean"
              }
            },
            "required": [
              "url",
              "label",
              "active"
            ]
          }
        },
        "path": {
          "type": [
            "string",
            "null"
          ],
          "description": "Base path for paginator generated URLs."
        },
        "per_page": {
          "type": "integer",
          "description": "Number of items shown per page.",
          "minimum": 0
        },
        "to": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Number of the last item in the slice.",
          "minimum": 1
        },
        "total": {
          "type": "integer",
          "description": "Total number of items being paginated.",
          "minimum": 0
        }
      },
      "required": [
        "current_page",
        "from",
        "last_page",
        "links",
        "path",
        "per_page",
        "to",
        "total"
      ]
    }
  },
  "required": [
    "data",
    "links",
    "meta"
  ]
}
```

```json
{
  "data": [
    {
      "id": 101,
      "import_source": null,
      "import_source_ref": null,
      "import_source_id": null,
      "data_import_id": null,
      "imported_at": null,
      "project_id": null,
      "name": "Checkout delivery estimate",
      "description": null,
      "type": null,
      "winning_direction": null,
      "external_id": null,
      "external_platform": null,
      "external_synced_at": null,
      "external_metadata": null,
      "created_at": null,
      "updated_at": null,
      "deleted_at": null
    }
  ],
  "links": {
    "first": null,
    "last": null,
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": null,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "example",
        "active": true
      }
    ],
    "path": null,
    "per_page": 1,
    "to": null,
    "total": 1
  }
}
```

### 400

Unsupported filter, sort, or include.

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "example": "Requested query option is not allowed."
    }
  },
  "required": [
    "message"
  ]
}
```

```json
{
  "message": "Requested query option is not allowed."
}
```

### 401

Unauthenticated

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Error overview."
    }
  },
  "required": [
    "message"
  ]
}
```

```json
{
  "message": "The request could not be completed."
}
```

### 403

Authorization error

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Error overview."
    }
  },
  "required": [
    "message"
  ]
}
```

```json
{
  "message": "The request could not be completed."
}
```

### 422

Validation error

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Errors overview."
    },
    "errors": {
      "type": "object",
      "description": "A detailed description of each field that failed validation.",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "message",
    "errors"
  ]
}
```

```json
{
  "message": "The request could not be completed.",
  "errors": {
    "name": [
      "The name field is required."
    ]
  }
}
```

### 429

Rate limit exceeded. Honor Retry-After before retrying.

Response headers:

```json
{
  "Retry-After": {
    "description": "Seconds before retrying.",
    "schema": {
      "type": "integer"
    }
  }
}
```

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "example": "Too Many Attempts."
    }
  },
  "required": [
    "message"
  ]
}
```

```json
{
  "message": "Too Many Attempts."
}
```

See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads.