Start a lab execution

POST https://rest.haasapi.com/v1/labs/{lab_id}/start

Queues the lab’s parameter sweep over a time window and answers 202 with the updated lab - poll GET /labs/{lab_id} until the status is terminal. Lab executions run MANY backtests; size the window and the lab’s configuration accordingly.

Requires the labs scope.

Request body

{
  "start_at": "2026-08-01T00:00:00Z",
  "end_at": "2026-08-02T00:00:00Z"
}

StartLabRequest

The request contract for POST /v1/labs/{lab_id}/start.

Field	Type	Description
start_at	string	Start of the window to backtest, RFC 3339 (e.g. 2026-08-01T00:00:00Z).
end_at	string	End of the window to backtest, RFC 3339. Must be after start_at.

Example request

curl "https://rest.haasapi.com/v1/labs/{lab_id}/start" \
  -X POST \
  -H "Authorization: Bearer hk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_at":"2026-08-01T00:00:00Z","end_at":"2026-08-02T00:00:00Z"}'

Response

202 Accepted - the job was queued; poll its status. Returns a LabDetail.

{
  "lab_id": "2f4f0f8a9df646c78be7a2a9f6d5b1c3",
  "name": "Scalper sweep BTC",
  "script_id": "7a4b2f91d6e53c8942a0bd7e1f5896c4",
  "algorithm": "intelligent",
  "status": "queued",
  "account_id": "af85799d-a214-4fd2-92ea-443c5eed18ad",
  "market_tag": "BINANCE_BTC_USDT",
  "interval": 5,
  "start_at": "2026-08-01T00:00:00Z",
  "end_at": "2026-08-15T00:00:00Z",
  "started_at": "2026-08-20T09:14:10Z",
  "scheduled_backtests": 100,
  "completed_backtests": 0,
  "parameters_count": 8,
  "enabled_parameters_count": 2,
  "config": {
    "max_population": 10,
    "max_generations": 10,
    "max_elites": 3
  },
  "cancel_reason": null,
  "created_at": "2026-08-20T09:12:04Z",
  "updated_at": "2026-08-20T11:47:33Z"
}

Fields

LabDetail

The single-lab shape: the list row plus the execution setup and a summary of the configuration - counts, not the parameter matrix itself.

Field	Type	Description
lab_id	string	Lab identifier - the id the lab endpoints accept.
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.
account_id	string, nullable	The account whose fees and wallet the lab’s backtests simulate. null until the lab was configured.
market_tag	string, nullable	The market the lab backtests - joins against market_tag on /v1/markets. null until the lab was configured.
interval	integer (int32), nullable	Chart interval in minutes. null until the lab was configured.
start_at	string, nullable	Start of the backtested window of the current/last execution, RFC 3339 UTC. null before the first start.
end_at	string, nullable	End of the backtested window of the current/last execution, RFC 3339 UTC. null before the first start.
started_at	string, nullable	When the current/last execution was started, RFC 3339 UTC. null before the first start.
scheduled_backtests	integer (int32)	Backtests the current/last execution scheduled.
completed_backtests	integer (int32)	Backtests completed so far.
parameters_count	integer (int32)	How many script parameters the lab knows about.
enabled_parameters_count	integer (int32)	How many of them are enabled for sweeping.
config	LabConfig	The execution sizing of the lab’s algorithm. null until the lab was configured.
cancel_reason	string, nullable	Why the last execution stopped early - ‘Cancelled by user’ for POST /cancel, a system reason for an automatic failure. null otherwise.
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.

LabConfig

The sizing knobs of the lab’s search - for intelligent labs the execution runs at most max_population * max_generations backtests.

Field	Type	Description
max_population	integer (int32)	Parameter combinations evaluated per generation.
max_generations	integer (int32)	Generations the search runs.
max_elites	integer (int32)	Top results carried into the next generation.

Errors

All errors are RFC 9457 problem documents.

Status	Description
400	The request is malformed (invalid limit, unusable cursor, …). (code: invalid_request) A field is missing or malformed, or end_at is not after start_at. (code: invalid_request)
401	Missing, malformed, disabled, or revoked API key. (code: invalid_api_key)
403	Your plan does not allow running labs. (code: forbidden)
404	No accessible lab with that id (also answered when the lab’s stored configuration cannot be loaded - the channel does not distinguish). (code: lab_not_found)
409	A request with this Idempotency-Key is still being processed. (code: idempotency_in_progress)
422	The Idempotency-Key was already used with a different request. (code: idempotency_key_reuse)
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"
}