# List samples

`GET /v0/labs/samples`

> **Authentication:** every request must send `X-ConfidentLims-APIKey`, `X-ConfidentLims-Timestamp` (unix seconds) and `X-ConfidentLims-Signature`, an HMAC-SHA256 signature of the request. The examples below call `sign_request()` from the [Request Signing guide](https://api.confidentcannabis.com/v0/docs/request-signing.md) — read it first. Request bodies are form-encoded, never JSON.

Return the samples belonging to this lab, most recent order first.

Results are paged: walk them with `start` and `limit` (maximum 100 per page) and keep requesting pages while `more_results` is `true`.

The filters combine, so a polling integration can watch for work with `status_id`, and an incremental sync can pass the `modified_since_time` it recorded on its last successful run.

## Query parameters

- `start` (integer, optional, default `0`) — Zero-based index of the first sample to return.
- `limit` (integer, optional, default `100`) — Maximum number of samples to return, up to 100.
- `status_id` (integer, optional) — Only return samples whose order is in this order status.
- `modified_since_time` (string, optional) — Only return samples modified after this time.
- `client_id` (integer, optional) — Only return samples belonging to this client.
- `regulator_batch_id` (string, optional) — Only return samples from this batch in the state's seed-to-sale tracking system.
- `harvest_id` (string, optional) — Only return samples from this harvest lot in the state's seed-to-sale tracking system.

## Responses

### 200 Success

Fields (alongside the `success: true` envelope flag):

- `samples` (array of objects)
  - `id` (string) — Sample ID
  - `order_id` (string) — Orders ID
  - `client_id` (integer) — Client ID
  - `lab` (object) — Lab
    - `id` (integer) — Lab ID
    - `name` (string) — Lab Name
  - `order_status_id` (integer) — Order Status ID
  - `order_status_name` (string) — Order Status Name
  - `sample_name` (string) — Name of Sample
  - `strain_name` (string) — Name of Sample Strain
  - `sample_industry_id` (integer) — Sample Industry ID
  - `sample_industry_name` (string) — Sample Industry Name
  - `sample_category_id` (integer) — Sample Category ID
  - `sample_category_name` (string) — Sample Category Name
  - `sample_type_id` (integer) — Sample Type ID
  - `sample_type_name` (string) — Sample Type Name
  - `sample_classification_id` (integer) — Sample Classification ID
  - `sample_classification_name` (string) — Sample Classification Name
  - `production_method_name` (string) — Production Method name
  - `production_method_id` (integer) — Production Method ID
  - `regulator_sample_id` (string) — Unique ID from the state's seed-to-sale tracking system of the sample tested by the lab
  - `regulator_batch_id` (string) — Unique ID from the state's seed-to-sale tracking system of the client's batch from which the sample tested by the lab came
  - `batch_id` (string) — Unique ID from the client's inventory management system of the client's batch from which the sample tested by the lab came
  - `harvest_id` (string) — Unique ID from the state's seed-to-sale tracking system of the client's harvest lot from which the sample tested by the lab came
  - `test_packages` (array of objects)
    - `id` (integer) — Unique ID for Test Package
    - `name` (string) — Test Package Name
    - `price` (number) — Package Price - if 0, call for price
    - `minimum_quantity` (number) — Minimum sample quantity required for testing
  - `last_modified` (timestamp) — Time this sample was last modified
  - `date_published` (timestamp) — Published Date [when sample was published]
  - `order_lims_id` (string) — Orders lims ID
  - `lims_id` (string) — Sample lims ID
- `more_results` (boolean) — True if more pages are available.

Example:

```json
{
  "success": true,
  "samples": [
    {
      "id": "2601-0143-1",
      "order_id": "2601-0143",
      "client_id": 812,
      "lab": {
        "id": 44,
        "name": "Cascade Analytics"
      },
      "order_status_id": 3,
      "order_status_name": "In Progress",
      "sample_name": "Blue Dream Flower",
      "strain_name": "Blue Dream",
      "sample_industry_id": 1,
      "sample_industry_name": "Cannabis & Hemp",
      "sample_category_id": 1,
      "sample_category_name": "Plant",
      "sample_type_id": 1,
      "sample_type_name": "Flower - Cured",
      "sample_classification_id": 9,
      "sample_classification_name": "Sativa Dominant",
      "production_method_id": 3,
      "production_method_name": "Greenhouse",
      "regulator_sample_id": "1A4060300003B71000001234",
      "regulator_batch_id": "1A4060300003B71000001180",
      "batch_id": "BD-2026-08-A",
      "harvest_id": "HARVEST-2026-07-BD",
      "test_packages": [
        {
          "id": 12,
          "name": "Compliance Panel",
          "price": 275.0,
          "minimum_quantity": 1
        }
      ],
      "last_modified": "2026-08-14T17:22:05",
      "date_published": null,
      "order_lims_id": "ORD-2026-0143",
      "lims_id": "S-2026-0143-1"
    },
    {
      "id": "2601-0142-1",
      "order_id": "2601-0142",
      "client_id": 807,
      "lab": {
        "id": 44,
        "name": "Cascade Analytics"
      },
      "order_status_id": 4,
      "order_status_name": "Completed",
      "sample_name": "Wedding Cake Live Rosin",
      "strain_name": "Wedding Cake",
      "sample_industry_id": 1,
      "sample_industry_name": "Cannabis & Hemp",
      "sample_category_id": 2,
      "sample_category_name": "Concentrates & Extracts",
      "sample_type_id": 34,
      "sample_type_name": "Rosin",
      "sample_classification_id": 4,
      "sample_classification_name": "Hybrid",
      "production_method_id": 46,
      "production_method_name": "Pressing",
      "regulator_sample_id": "1A4060300003B71000001101",
      "regulator_batch_id": "1A4060300003B71000001099",
      "batch_id": "WC-2026-07-C",
      "harvest_id": "HARVEST-2026-06-WC",
      "test_packages": [
        {
          "id": 15,
          "name": "Potency Only",
          "price": 85.0,
          "minimum_quantity": 1
        }
      ],
      "last_modified": "2026-08-11T09:04:41",
      "date_published": "2026-08-11T09:04:41",
      "order_lims_id": "ORD-2026-0142",
      "lims_id": "S-2026-0142-1"
    }
  ],
  "more_results": false
}
```

### 400 Bad request

The request was malformed or failed validation. Validation failures include per-field messages in `error_details`. Possible `error_code` values: `invalid_request`, `request_too_old`.

### 401 Unauthorized

Authentication failed. Possible `error_code` values: `missing_api_key`, `invalid_api_key`, `invalid_credentials_type`, `api_access_restricted`, `api_access_denied`, `missing_signature`, `missing_timestamp`, `invalid_timestamp`, `invalid_signature`.

### 403 Permission denied

The API key is valid but does not have permission for this endpoint (for example, a client key calling a labs endpoint). Possible `error_code` values: `permission_denied`.

## Examples

### cURL

```bash
# X-ConfidentLims-Signature: see the Request Signing guide - https://api.confidentcannabis.com/v0/docs/request-signing.md
curl -X GET 'https://api.confidentcannabis.com/v0/labs/samples' \
  -H 'X-ConfidentLims-APIKey: YOUR_API_KEY' \
  -H 'X-ConfidentLims-Timestamp: UNIX_TIMESTAMP' \
  -H 'X-ConfidentLims-Signature: REQUEST_SIGNATURE'
```

### Python

```python
import time
import requests

# sign_request() is defined in the Request Signing guide:
# https://api.confidentcannabis.com/v0/docs/request-signing.md
from sign_request import sign_request

API_KEY = 'YOUR_API_KEY'
API_SECRET = 'YOUR_API_SECRET'
path = '/v0/labs/samples'

params = {
    # optional query params go here - they are signed too
}

headers = {'X-ConfidentLims-Timestamp': str(int(time.time()))}
headers['X-ConfidentLims-Signature'] = sign_request(
    'GET', path, headers, params, API_KEY, API_SECRET)
headers['X-ConfidentLims-APIKey'] = API_KEY

response = requests.get(
    'https://api.confidentcannabis.com' + path,
    headers=headers,
    params=params,
)
print(response.json())
```

### JavaScript

```javascript
// signRequest() is defined in the Request Signing guide:
// https://api.confidentcannabis.com/v0/docs/request-signing.md
import { signRequest } from './sign_request.js';

const API_KEY = 'YOUR_API_KEY';
const API_SECRET = 'YOUR_API_SECRET';
const path = "/v0/labs/samples";

const params = {
  // optional query params go here - they are signed too
};

const headers = { 'X-ConfidentLims-Timestamp': String(Math.floor(Date.now() / 1000)) };
headers['X-ConfidentLims-Signature'] = signRequest(
  "GET", path, headers, params, API_KEY, API_SECRET);
headers['X-ConfidentLims-APIKey'] = API_KEY;

const response = await fetch(`https://api.confidentcannabis.com${path}?${new URLSearchParams(params)}`, {
  headers,
});
console.log(await response.json());
```

---

HTML version: https://api.confidentcannabis.com/v0/docs/labs/get-samples  
OpenAPI spec for this section: https://api.confidentcannabis.com/v0/docs/labs/openapi.json  
Request Signing guide: https://api.confidentcannabis.com/v0/docs/request-signing.md