Skip to content

How to Use the Sample API

You can find the full Sample API Reference here.

Endpoint

GET /mave/sample/v1

Request

Query Parameters

Parameter Type Required Description
run_ids string Yes One or more sequencing run IDs provided as repeated query parameters (e.g. ?run_ids=50955 or ?run_ids=50955&run_ids=50956&run_ids=50957)
metadata string No Metadata returned from a previous response for pagination

Example Requests

GET /mave/sample/v1?run_ids=50955

GET /mave/sample/v1?run_ids=50955&run_ids=50956&run_ids=50957

GET /mave/sample/v1?run_ids=50955&run_ids=50956&metadata=<metadata>

Response Structure

Field Description
samples Array of sample objects, one per record returned from MLWH
metadata Metadata returned from a previous response for pagination
total_rows Total number of rows returned from MLWH
row_count Number of rows returned in this response
limit Limit applied to the response
consumed Number of rows consumed from the response

Sample Object Fields

Field Description
id_study_lims Study identifier
id_run Sequencing run ID
name Sample name
supplier_name Supplier-provided sample identifier
sequencing_technology Sequencing platform identifier (e.g. element)
irods_root_collection Root iRODS storage location
irods_data_relative_path Relative iRODS file path
paired_read Indicates paired-end sequencing (1 = paired, 0 = single)
num_reads Number of sequencing reads associated with a sample for a given run/lane
lane Sequencing lane

Pagination

Use limit and offset to page through large result sets.

GET /mave/sample/v1?run_ids=50955&limit=50&offset=100

This returns up to 50 records, starting from the 101st record in the result set.

Note

Default values for limit and offset are applied by the API if they are omitted from the request.

Error Responses

Validation Error

Returned when the required run_ids parameter is missing or invalid.

HTTP Status: 400 Bad Request

{
  "error": "VALIDATION_ERROR",
  "message": "run_ids is required"
}

Run Not Found

Returned when no sample records exist in MLWH for the supplied run ID(s).

HTTP Status: 404 Not Found

{
  "error": "NOT_FOUND",
  "message": "No sample records found"
}

Authorisation Failure

Returned when the caller is not authenticated or not authorised to access the API.

HTTP Status: 401 Unauthorized or 403 Forbidden

{
  "error": "UNAUTHORIZED",
  "message": "Access denied"
}

See Authentication & Access for details on obtaining credentials.

MLWH Failure

Returned when MLWH is unavailable or a request times out.

HTTP Status: 503 Service Unavailable or 504 Gateway Timeout

{
  "error": "DOWNSTREAM_FAILURE",
  "message": "Failed to retrieve sample data from MLWH"
}

Authentication

Both APIs use the same credentials. See Authentication & Access for the full OAuth 2.0 client credentials flow.

Example Python Usage

import requests

response = requests.get(
    "https://api.example.com/mave/sample/v1",
    params={
        "run_ids": "50955,50956",
        "limit": 100,
        "offset": 0
    },
    headers={
        "Authorization": "Bearer <access_token>"
    }
)

print(response.json())

Support

For issues related to:

  • Missing sample records
  • MLWH data inconsistencies
  • API access or authentication
  • Downstream failures

please contact the MAVE team.