List labs

GET https://rest.haasapi.com/v1/labs

Returns the user’s labs (parameter-optimization runs) as lean rows, sorted by lab_id and paged by a keyset cursor. The lab_id is the join key the lab endpoints take. Account, market and window live on the single-lab endpoint.

Requires the read scope.

Query parameters

Parameter	Type	Required	Description
limit	integer	no	Page size, 1–500. Defaults to 100.
cursor	string	no	Opaque cursor from a previous response’s next_cursor.

Example request

curl "https://rest.haasapi.com/v1/labs?limit=100" \
  -H "Authorization: Bearer hk_live_YOUR_KEY"

Response

200 OK. Returns a LabsPage.

{
  "data": [
    {
      "lab_id": "2f4f0f8a9df646c78be7a2a9f6d5b1c3",
      "name": "Scalper sweep BTC",
      "script_id": "7a4b2f91d6e53c8942a0bd7e1f5896c4",
      "algorithm": "intelligent",
      "status": "completed",
      "scheduled_backtests": 100,
      "completed_backtests": 100,
      "created_at": "2026-08-20T09:12:04Z",
      "updated_at": "2026-08-20T11:47:33Z"
    }
  ],
  "next_cursor": null
}

Fields

LabsPage

The public contract for /v1/labs - read and lifecycle only in this tranche: lab creation and parameter-matrix editing are deliberately absent (the matrix shape needs its own design pass). Same single-source-of-truth pattern as the other V1 DTOs.

Like bots and scripts, the lab list is MUTABLE while a client pages it, so its cursor is a keyset cursor - see V1LabsResource.

Field	Type	Description
data	array of Lab	One page of the user’s labs, sorted by lab_id.
next_cursor	string, nullable	Pass as cursor to fetch the next page; null on the last page. Opaque - never construct or decode one.

Lab

The list row. Account, market and window live only on the single-lab shape - the internal list record does not carry them.

Field	Type	Description
lab_id	string	Lab identifier - the id the lab endpoints accept. Copy it from this endpoint; never construct one.
name	string	User-chosen lab name.
script_id	string	The HaasScript whose parameter space the lab explores.
algorithm	LabAlgorithm	How the lab walks the parameter space.
status	LabStatus	Execution status. completed, cancelled and failed are terminal.
scheduled_backtests	integer (int32)	Backtests the current/last execution scheduled.
completed_backtests	integer (int32)	Backtests completed so far.
created_at	string, nullable	When the lab was created, RFC 3339 UTC.
updated_at	string, nullable	When the lab was last updated, RFC 3339 UTC.

LabAlgorithm

How a lab searches the parameter space it was given.

Value	Description
brute_force	Every combination of the swept values.
intelligent	A genetic search sized by the config.
random	Random samples.
cluster	Clustered sampling.

LabStatus

Where a lab stands. Poll until a TERMINAL status, not until completed - a lab can also end cancelled or failed.

Value	Description
created	Never started.
queued	Waiting for an executor.
running	Executing.
completed	Finished successfully. Terminal.
cancelled	Cancelled before finishing. Terminal.
failed	Execution failed. Terminal.

Errors

All errors are RFC 9457 problem documents.

Status	Description
400	The request is malformed (invalid limit, unusable cursor, …). (code: invalid_request)
401	Missing, malformed, disabled, or revoked API key. (code: invalid_api_key)
500	An unexpected error inside the API. Nothing about the request caused it; retry, and quote the instance value if it persists. (code: internal_error)
502	An internal service answered in a way the API could not serve. Retry. (code: upstream_error)
503	The request could not be served right now. Retry with the same key - do not discard it. (code: temporarily_unavailable)
504	An internal service did not answer within the deadline. Retry with backoff. (code: upstream_timeout)

{
  "type": "https://docs.haasapi.com/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request is malformed (invalid limit, unusable cursor, …).",
  "code": "invalid_request"
}