Expand and Sort

Expanding and Sorting

Many list endpoints support $expand and $sort query parameters to control the shape and order of the response data.

$expand

The $expand parameter replaces ID references in the response with their full objects. This reduces the number of API calls needed to get related data.

Usage: Pass a comma-separated list of expand values:

GET /api/v1/samples?$expand=sampleType,user

Without $expand, a sample might return:

{
  "sampleTypeID": 42,
  "userID": 7,
  "name": "My Sample"
}

With $expand=sampleType,user, the same sample returns:

{
  "sampleTypeID": 42,
  "sampleType": {
    "sampleTypeID": 42,
    "name": "Chemical Compound",
    "backgroundColor": "666"
  },
  "userID": 7,
  "user": {
    "userID": 7,
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "name": "My Sample"
}

The available $expand values differ per endpoint and are documented in each endpoint's description.

$sort

The $sort parameter controls the order of results. Pass a field name to sort ascending, or append DESC to sort descending.

Ascending (default):

GET /api/v1/samples?$sort=name

Descending:

GET /api/v1/samples?$sort=name DESC

The available sort fields differ per endpoint. The API reference documentation lists the available fields for each endpoint in the $sort parameter description.

Other query parameters

Endpoints that accept $expand and $sort also support these additional parameters:

Notes

• Not all endpoints support $expand and $sort. These parameters are only available on endpoints that accept a FieldOptions parameter.
• Using an unsupported expand or sort value will result in a 400 Bad Request error.
• The $sort parameter validates field names against a whitelist specific to each endpoint.