# List lab observations

Operation ID: `diagnostics.listDiagnostics`

Return lab Observations for a patient. A PATIENT-pool caller may only pass their own FHIR patient id as {patient_id} — resolved server-side from their verified Cognito subject, never trusted from the path; a mismatch is rejected with 403. Provider, field agent, and tenant-admin callers may pass any {patient_id}.

## Public method

`list`

Signature: `diagnostics.list(patientId)`

Return type: `Promise<ListDiagnosticsResponse>`

## Authentication

Classification: **AUTHENTICATED**

Schemes: `bearerAuth`

## Prerequisites

None documented.

## HTTP

`GET /patients/{patient_id}/diagnostics`

## Path parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `patient_id` | `string` | Yes |  |  |  | No |  |

## Query parameters

None.

## Body parameters

None.

Request model: None.

## Request example

None declared in canonical OpenAPI.

## Success responses

| Status | Shape | Content type | Description |
|---|---|---|---|
| `200` | [`diagnostics.ListDiagnosticsResponse`](../models/diagnostics.ListDiagnosticsResponse.md) | application/json | Lab observations for the patient |

## Success response examples

### 200

```json
{
  "observations": [
    {
      "display": "SARS-CoV-2 RNA",
      "effective_datetime": "2026-08-10T12:00:00Z",
      "interpretation": "NEG",
      "loinc_code": "94500-6",
      "notes": "Synthetic diagnostic observation",
      "observation_id": "observation-example-001",
      "reference_range": {
        "high": 1,
        "low": 0,
        "text": "Negative: less than 1.0 index",
        "unit": "index"
      },
      "status": "final",
      "value_boolean": null,
      "value_coding": {},
      "value_quantity": 0.12,
      "value_string": null,
      "value_unit": "index"
    }
  ],
  "total": 1
}
```

## Common errors

| Status | Shape | Content type | Description |
|---|---|---|---|
| `401` | [`diagnostics.ErrorResponse`](../models/diagnostics.ErrorResponse.md) | application/json | Authorization required — missing or invalid Bearer JWT |
| `403` | [`diagnostics.ErrorResponse`](../models/diagnostics.ErrorResponse.md) | application/json | A PATIENT-pool caller attempted to access another patient's data |
| `404` | [`diagnostics.ErrorResponse`](../models/diagnostics.ErrorResponse.md) | application/json | The PATIENT-pool caller's own FHIR Patient record could not be resolved |
| `500` | [`diagnostics.ErrorResponse`](../models/diagnostics.ErrorResponse.md) | application/json | Internal server error |

## Error examples

### 401 — Missing or invalid access token

```json
{
  "error": "Authorization required"
}
```

### 403 — The caller's own FHIR patient id does not match patient_id

```json
{
  "error": "Cannot access another patient's data"
}
```

### 404 — The caller's own patient record was not found

```json
{
  "error": "Patient not found"
}
```

### 500 — Unexpected service failure (sanitized example)

```json
{
  "error": "Internal server error"
}
```

## NodeJS / TypeScript implementation

```ts
import { HCSDK } from "@healthcloudai/hc-sdk";
```

```ts
const patientId = "<PATIENT_ID>";

const result = await diagnostics.list(patientId);
```

## cURL

```bash
curl -X GET \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  'https://dev-api-diagnostics.health.cloud/patients/%3CPATIENT_ID%3E/diagnostics'
```

## Notes

None.

## Prepared Test Console scenario

No canonical scenario is currently associated.

## Real response

No approved real integration response is currently published. Unapproved candidates are never rendered as examples.