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

string

required

Convex ID of the lab this experiment belongs to.

string

required

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

string

Convex ID of the parent project, if applicable.

string

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

string

default:"CPU"

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

object

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

Show Config fields

string

GPU type override.

number

Batch size for data loading.

number

Number of training epochs.

string

Script path to execute on the pod.

object

Environment variables to set.

string

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

string

default:"normal"

Queue priority: critical, high, normal, low.

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,
});

object

Show Experiment object

string

required

Convex document ID.

string

required

Parent lab ID.

string

Parent project ID.

string

required

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

string

required

Experiment title.

string

required

Current status.

string

Summary of results after completion.

string

GPU type or CPU.

string

JSON-encoded configuration.

string

Queue priority.

number

Position in the queue (when queued).

number

Estimated runtime.

number

Actual runtime (after completion).

number

Creation timestamp (ms).

number

Completion timestamp (ms).

List Experiments

string

required

Lab ID to list experiments for.

string

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

string

Filter by parent project.

number

default:"50"

Results per page.

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).

string

Updated title.

string

New status. Valid transitions depend on current status.

string

Result summary (typically set on completion).

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

string

required

Experiment Convex ID.

string

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

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 }

object

Show Metrics object

number

Total runtime in seconds.

number

Average GPU utilization (0-1).

number

Peak VRAM usage in GB.

number

Total compute cost in USD.

number

Total log entries.

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