Pagination, filtering, and errors
Clearline confirms supported pagination, filtering, rate limits, and error behavior during read-only API onboarding. Access is optional, tenant-scoped, and disabled unless provisioned by Clearline.
Endpoint and response examples below are placeholders until Clearline confirms the exact implementation for your tenant.
Pagination#
List endpoints may use page-based pagination.
GET /api/v1/samples?page=2&page_size=50 HTTP/1.1
Host: api.example.clearlinelims.test
Authorization: Bearer EXAMPLE_READ_ONLY_TOKEN
Accept: application/json
Typical pagination metadata may include:
{
"page": 2,
"page_size": 50,
"total_pages": 8,
"total_count": 391
}
Use a conservative page size unless Clearline Support confirms a higher limit for your integration.
Filtering#
Supported filters vary by endpoint and tenant. Common read-only filters may include:
| Filter | Typical use |
|---|---|
updated_since | Retrieve records changed since a known timestamp. |
received_since | Retrieve recently received samples where enabled. |
published_since | Retrieve recently published reports where enabled. |
status | Limit results to supported customer-facing statuses. |
client_id | Limit records to an authorized client scope. |
project_id | Limit records to an authorized project scope. |
Avoid polling aggressively. Clearline Support will confirm expected query frequency during onboarding.
Error responses#
Typical error responses may include:
| Status | Meaning | Recommended action |
|---|---|---|
400 | Invalid filter, date, or pagination value. | Correct the request and retry. |
401 | Missing, expired, revoked, or invalid credential. | Check credential handling; contact Clearline Support if needed. |
403 | Token is authenticated but the requested resource is outside the provisioned scope. | Confirm the requested tenant, client, project, or data area. |
404 | The record was not found or is not available within the token scope. | Confirm the identifier and access scope. |
429 | Rate limit reached. | Back off and retry later according to onboarding guidance. |
500 | Service error. | Retry cautiously; contact Clearline Support if repeated. |
Support escalation#
When contacting Clearline Support about API behavior, include:
- timestamp and timezone;
- endpoint path without secrets;
- HTTP status code;
- correlation or request ID if provided;
- tenant and integration name;
- sanitized request parameters;
- whether the issue is blocking a production workflow.
Never include bearer tokens or downloaded sensitive data in the support ticket.