Experiments API

Shipped today: GET /v1/experiments, POST /v1/experiments, plus the sub-collections /experiments/costs, /experiments/queues, /experiments/templates (GET + POST each). Per-experiment routes (GET /v1/experiments/{id}, /logs, /metrics) are planned, not yet live. Stream logs via the experiment-detail view in the web app or the Convex experiments.getLogs query.

Experiments are the core research unit in Hubify. Each experiment runs on GPU compute (or CPU), streams logs in real time, passes through QC gates, and stores results back to the lab.

Experiment Status Lifecycle

queued → running → pass / fail / blocked

Status	Description
`queued`	Waiting for a compute pod or manual trigger
`running`	Actively executing on a pod
`pass`	Completed successfully and passed QC
`fail`	Completed with errors or failed QC
`blocked`	Waiting on a dependency or manual unblock

Create an Experiment

labId

string

required

Convex ID of the lab this experiment belongs to.

title

string

required

Human-readable experiment title (e.g., “MCMC Chain, Planck 2018 + BAO”).

projectId

string

Convex ID of the parent project, if applicable.

experimentId

string

Custom identifier (e.g., “EXP-054”). Auto-generated if omitted.

computeMode

string

default:"CPU"

Compute target: H200, H100, A100, or CPU.

config

object

Experiment configuration as a JSON object. Stored as a string internally.

Show Config fields

gpu_type

string

GPU type override.

batch_size

number

Batch size for data loading.

epochs

number

Number of training epochs.

script

string

Script path to execute on the pod.

env

object

Environment variables to set.

template

string

Experiment template name (e.g., mcmc, anomaly-sweep, fisher-forecast).

priority

string

default:"normal"

Queue priority: critical, high, normal, low.

estimatedSeconds

number

Estimated runtime in seconds. Used for scheduling and cost projection.

curl -X POST https://www.hubify.com/api/v1/experiments \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labId": "j57a8k9m2n3p4q5r",
    "title": "MCMC Chain, Planck 2018 + BAO",
    "experimentId": "EXP-054",
    "computeMode": "H200",
    "config": {
      "script": "run_cobaya.py",
      "batch_size": 1,
      "env": {"COBAYA_PACKAGES": "/workspace/packages"}
    },
    "priority": "high",
    "estimatedSeconds": 7200
  }'

const experiment = await hubify.experiments.create({
  labId: "j57a8k9m2n3p4q5r",
  title: "MCMC Chain, Planck 2018 + BAO",
  experimentId: "EXP-054",
  computeMode: "H200",
  config: {
    script: "run_cobaya.py",
    batch_size: 1,
    env: { COBAYA_PACKAGES: "/workspace/packages" },
  },
  priority: "high",
  estimatedSeconds: 7200,
});

data

object

Show Experiment object

_id

string

required

Convex document ID.

labId

string

required

Parent lab ID.

projectId

string

Parent project ID.

experimentId

string

required

Display identifier (e.g., “EXP-054”).

title

string

required

Experiment title.

status

string

required

Current status.

result

string

Summary of results after completion.

computeMode

string

GPU type or CPU.

config

string

JSON-encoded configuration.

priority

string

Queue priority.

queuePosition

number

Position in the queue (when queued).

estimatedSeconds

number

Estimated runtime.

runTimeSeconds

number

Actual runtime (after completion).

createdAt

number

Creation timestamp (ms).

completedAt

number

Completion timestamp (ms).

List Experiments

labId

string

required

Lab ID to list experiments for.

status

string

Filter by status: queued, running, pass, fail, blocked.

projectId

string

Filter by parent project.

limit

number

default:"50"

Results per page.

cursor

string

Pagination cursor.

curl "https://www.hubify.com/api/v1/experiments?labId=j57a8k9m2n3p4q5r&status=running" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const experiments = await hubify.experiments.list({
  labId: "j57a8k9m2n3p4q5r",
  status: "running",
});

Get an Experiment

curl https://www.hubify.com/api/v1/experiments/EXP-054 \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const experiment = await hubify.experiments.get({ experimentId: "EXP-054" });

Update an Experiment

Update metadata or status of an experiment. Use this to manually transition status (e.g., unblock a blocked experiment).

title

string

Updated title.

status

string

New status. Valid transitions depend on current status.

result

string

Result summary (typically set on completion).

priority

string

Updated priority.

curl -X PATCH https://www.hubify.com/api/v1/experiments/EXP-054 \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "queued",
    "priority": "critical"
  }'

await hubify.experiments.update({
  experimentId: "EXP-054",
  status: "queued",
  priority: "critical",
});

Delete an Experiment

Delete an experiment and its associated logs. Does not delete figures generated by the experiment.

curl -X DELETE https://www.hubify.com/api/v1/experiments/EXP-054 \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

await hubify.experiments.delete({ experimentId: "EXP-054" });

Experiment Logs

Stream or retrieve logs for a running or completed experiment.

List Logs

experimentId

string

required

Experiment Convex ID.

level

string

Filter by log level: info, warn, error, debug.

limit

number

default:"100"

Number of log entries to return.

curl "https://www.hubify.com/api/v1/experiments/EXP-054/logs?level=error&limit=50" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const logs = await hubify.experiments.getLogs({
  experimentId: "EXP-054",
  level: "error",
  limit: 50,
});

// Real-time log subscription via Convex
client.onUpdate(
  api.experimentLogs.list,
  { experimentId: "j57a8k9m2n3p4q5r" },
  (logs) => {
    logs.forEach((log) => console.log(`[${log.level}] ${log.message}`));
  }
);

Experiment Metrics

After an experiment completes, metrics are available in the result and associated log entries.

curl https://www.hubify.com/api/v1/experiments/EXP-054/metrics \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const metrics = await hubify.experiments.getMetrics({
  experimentId: "EXP-054",
});
// { runtime: 3847, gpuUtilization: 0.94, peakVram: 78.2, costUsd: 4.27 }

data

object

Show Metrics object

runtime

number

Total runtime in seconds.

gpuUtilization

number

Average GPU utilization (0-1).

peakVram

number

Peak VRAM usage in GB.

costUsd

number

Total compute cost in USD.

logCount

number

Total log entries.

errorCount

number

Error-level log entries.

Overview

Labs

Data

Compute

Lab Ops

Experiments

Experiments API

Experiment Status Lifecycle

Create an Experiment

List Experiments

Get an Experiment

Update an Experiment

Delete an Experiment

Experiment Logs

List Logs

Experiment Metrics

​Experiments API

​Experiment Status Lifecycle

​Create an Experiment

​List Experiments

​Get an Experiment

​Update an Experiment

​Delete an Experiment

​Experiment Logs

​List Logs

​Subscribe to Logs (Real-Time)

​Experiment Metrics

Experiments API

Experiment Status Lifecycle

Create an Experiment

List Experiments

Get an Experiment

Update an Experiment

Delete an Experiment

Experiment Logs

List Logs

Subscribe to Logs (Real-Time)

Experiment Metrics