# Get observation

GET /observations/{observation}. Parameters, permissions, request and response schemas.

`GET /observations/{observation}`

Get observation. 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                                                                                                                              |
| ------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `observation` | path     | Yes      | The observation ID                                                                                                                       |
| `include`     | query    | No       | Comma-separated relationships or counts. Allowed: insightsCount, screenAnnotationsCount, pagesCount, insights, screenAnnotations, pages. |

### observation

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

### include

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

## Example request

```bash
curl --request GET 'https://api.example.test/api/observations/1' \
  --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

`ObservationResource`

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "project_id": {
          "type": "integer"
        },
        "research_collection_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "user_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "source_type": {
          "type": "string"
        },
        "source_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "source_item_key": {
          "type": [
            "string",
            "null"
          ]
        },
        "source_label": {
          "type": [
            "string",
            "null"
          ]
        },
        "evidence_kind": {
          "type": [
            "string",
            "null"
          ]
        },
        "evidence_payload": {
          "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"
            }
          ]
        },
        "confidence": {
          "type": [
            "string",
            "null"
          ]
        },
        "observed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "locked": {
          "type": "boolean"
        },
        "accepted_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "accepted_by": {
          "type": [
            "integer",
            "null"
          ]
        },
        "dismissed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "dismissed_by": {
          "type": [
            "integer",
            "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"
        },
        "review_status": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "project_id",
        "research_collection_id",
        "user_id",
        "name",
        "description",
        "source_type",
        "source_id",
        "source_item_key",
        "source_label",
        "evidence_kind",
        "evidence_payload",
        "confidence",
        "observed_at",
        "locked",
        "accepted_at",
        "accepted_by",
        "dismissed_at",
        "dismissed_by",
        "created_at",
        "updated_at",
        "deleted_at",
        "review_status"
      ],
      "title": "ObservationResource"
    }
  },
  "required": [
    "data"
  ]
}
```

```json
{
  "data": {
    "id": 101,
    "project_id": 101,
    "research_collection_id": null,
    "user_id": null,
    "name": "Checkout delivery estimate",
    "description": null,
    "source_type": "example",
    "source_id": null,
    "source_item_key": null,
    "source_label": null,
    "evidence_kind": null,
    "evidence_payload": null,
    "confidence": null,
    "observed_at": null,
    "locked": true,
    "accepted_at": null,
    "accepted_by": null,
    "dismissed_at": null,
    "dismissed_by": null,
    "created_at": null,
    "updated_at": null,
    "deleted_at": null,
    "review_status": "example"
  }
}
```

### 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."
}
```

### 404

Not found

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.