Loops API reference

Every Loops API call is authenticated with BASETEN_API_KEY. Resources nest as: sessions own runs and samplers; runs own checkpoints; deployments are produced from checkpoints. Auth scope varies per route; the per-route subsections name it explicitly. The HTTP API calls trainer servers “runs”; the Python SDK exposes the same value as trainer_server_id. Both names refer to the same resource ID. Legacy /v1/trainer_sessions/* routes still work for backwards compatibility, but the /v1/loops/* paths documented here are canonical.

Routes

Method	Path	Purpose	Auth scope
`POST`	`/v1/loops/sessions`	Creates a Loops session for the given training project.	`manage_org_training_projects`
`GET`	`/v1/loops/sessions/{session_id}`	Fetch a Loops session by ID.	`manage_org_training_projects`
`POST`	`/v1/loops/runs`	Creates a Loops run with an associated sampler in the given session.	`manage_org_training_projects`
`GET`	`/v1/loops/runs`	List Loops runs visible to the requesting user, optionally filtered by run id and/or base model.	`manage_own_user_or_service_account`
`GET`	`/v1/loops/runs/{run_id}`	Fetch a Loops run by ID. Always includes the paired sampler.	`manage_org_training_projects`
`POST`	`/v1/loops/samplers`	Creates a standalone Loops sampler not linked to a run.	`manage_org_training_projects`
`GET`	`/v1/loops/samplers`	List Loops samplers visible to the requesting user.	`manage_own_user_or_service_account`
`GET`	`/v1/loops/samplers/{sampler_id}`	Fetch a Loops sampler by ID.	`manage_org_training_projects`
`GET`	`/v1/loops/checkpoints`	List Loops checkpoints filtered by run id, base model, or bt:// URI. Provide exactly one filter.	`manage_own_user_or_service_account`
`GET`	`/v1/loops/checkpoints/{checkpoint_id}/files`	Get presigned URLs for the files under a Loops checkpoint. Returns a paginated list.	`manage_org_training_projects`
`GET`	`/v1/loops/deployments`	List the caller’s active Loops deployments. Excludes deployments whose latest status is stopped.	`manage_org_training_projects`
`POST`	`/v1/loops/deployments/{deployment_id}/deactivate`	Shut down a Loops deployment by ID. Saved checkpoints remain accessible.	`manage_org_training_projects`
`GET`	`/v1/loops/deployments/{deployment_id}`	Fetch a Loops deployment by ID, including its latest status.	`manage_org_training_projects`

POST /v1/loops/sessions

Creates a Loops session for the given training project. Auth scope: manage_org_training_projects. Request body:

Field	Type	Required	Description
`training_project_id`	string	no	ID of the training project to associate with. If omitted, a default project is created for the org.

Response body:

Field	Type	Description
`session.id`	string	The Loops session ID.

Example:

curl --request POST \
  --url https://api.baseten.co/v1/loops/sessions \
  --header "Authorization: Api-Key $BASETEN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

{
  "session": {
    "id": "sess_xyz789"
  }
}

GET /v1/loops/sessions/

Fetch a Loops session by ID. Auth scope: manage_org_training_projects. Path parameters:

Parameter	Type	Description
`session_id`	string	Loops session ID.

Response body:

Field	Type	Description
`session.id`	string	The Loops session ID.

Example:

curl --request GET \
  --url https://api.baseten.co/v1/loops/sessions/sess_xyz789 \
  --header "Authorization: Api-Key $BASETEN_API_KEY"

{
  "session": {
    "id": "sess_xyz789"
  }
}

POST /v1/loops/runs

Creates a Loops run with an associated sampler in the given session. Auth scope: manage_org_training_projects. Request body:

Field	Type	Required	Description
`session_id`	string	yes	ID of the Loops session this run belongs to.
`base_model`	string	yes	Base model ID (for example, `Qwen/Qwen3-8B`).
`max_seq_len`	integer	no	Maximum prompt length in tokens the run must handle. Set this to the longest training example you plan to send. Defaults to `131072`.
`lora_rank`	integer	no	LoRA rank. Defaults to `64`.
`seed`	integer	no	Random seed for reproducibility.
`scale_down_delay_seconds`	integer	no	Seconds of inactivity before the run scales to zero. Must be positive. Defaults to `3600`.
`path`	string	no	Optional `bt://` URI of an existing trainer-target checkpoint to resume training from. Form: `bt://loops:<run_id>/weights/<checkpoint_name>`.

Response body:

Field	Type	Description
`run.id`	string	The run ID.
`run.base_url`	string	Base URL clients use to reach the run.
`run.sampler.id`	string	The paired sampler ID.
`run.sampler.base_url`	string	Base URL clients use to reach the paired sampler.

Example:

curl --request POST \
  --url https://api.baseten.co/v1/loops/runs \
  --header "Authorization: Api-Key $BASETEN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "session_id": "sess_xyz789",
    "base_model": "Qwen/Qwen3-8B",
    "lora_rank": 64,
    "max_seq_len": 131072
  }'

{
  "run": {
    "id": "k4q95w5",
    "base_url": "https://model-abc123.api.baseten.co/deployment/dep456/sync",
    "sampler": {
      "id": "samp_def789",
      "base_url": "https://model-ghi012.api.baseten.co/deployment/dep345/sync"
    }
  }
}

GET /v1/loops/runs

List Loops runs visible to the requesting user, optionally filtered by run id and/or base model. Auth scope: manage_own_user_or_service_account. Query parameters:

Parameter	Type	Required	Description
`run_id`	string	no	Filter by run ID.
`base_model`	string	no	Filter runs by base model name.

Response body:

Field	Type	Description
`runs`	array	List of runs.
`runs[].run_id`	string	The run ID.
`runs[].session_id`	string	The session ID this run belongs to.
`runs[].base_model`	string	The HuggingFace base model the run is fine-tuning.

Example:

curl --request GET \
  --url "https://api.baseten.co/v1/loops/runs?base_model=Qwen%2FQwen3-8B" \
  --header "Authorization: Api-Key $BASETEN_API_KEY"

{
  "runs": [
    {
      "run_id": "k4q95w5",
      "session_id": "sess_xyz789",
      "base_model": "Qwen/Qwen3-8B"
    }
  ]
}

GET /v1/loops/runs/

Fetch a Loops run by ID. Always includes the paired sampler. Every run is provisioned with one at create time. Auth scope: manage_org_training_projects. Path parameters:

Parameter	Type	Description
`run_id`	string	Loops run ID.

Response body:

Field	Type	Description
`run.id`	string	The run ID.
`run.base_url`	string	Base URL clients use to reach the run.
`run.sampler.id`	string	The paired sampler ID.
`run.sampler.base_url`	string	Base URL clients use to reach the paired sampler.

Example:

curl --request GET \
  --url https://api.baseten.co/v1/loops/runs/k4q95w5 \
  --header "Authorization: Api-Key $BASETEN_API_KEY"

{
  "run": {
    "id": "k4q95w5",
    "base_url": "https://model-abc123.api.baseten.co/deployment/dep456/sync",
    "sampler": {
      "id": "samp_def789",
      "base_url": "https://model-ghi012.api.baseten.co/deployment/dep345/sync"
    }
  }
}

POST /v1/loops/samplers

Creates a standalone Loops sampler not linked to a run. Auth scope: manage_org_training_projects. Request body:

Field	Type	Required	Description
`session_id`	string	yes	ID of the Loops session this sampler belongs to.
`base_model`	string	yes	Base model ID for standalone samplers (for example, for baselines).
`max_seq_length`	integer	no	Maximum prompt length in tokens the sampler must handle. Omit to use the default for the base model.
`model_path`	string	no	Optional `bt://` URI of an existing sampler-target checkpoint to load weights from on startup. Form: `bt://loops:<run_id>/sampler_weights/<checkpoint_name>`.

Response body:

Field	Type	Description
`sampler.id`	string	The sampler ID.
`sampler.base_url`	string	Base URL clients use to reach the sampler.

Example:

curl --request POST \
  --url https://api.baseten.co/v1/loops/samplers \
  --header "Authorization: Api-Key $BASETEN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "session_id": "sess_xyz789",
    "base_model": "Qwen/Qwen3-8B",
    "model_path": "bt://loops:k4q95w5/sampler_weights/step-100"
  }'

{
  "sampler": {
    "id": "samp_def789",
    "base_url": "https://model-ghi012.api.baseten.co/deployment/dep345/sync"
  }
}

GET /v1/loops/samplers

List Loops samplers visible to the requesting user. Auth scope: manage_own_user_or_service_account. Response body:

Field	Type	Description
`samplers`	array	List of samplers.
`samplers[].id`	string	The sampler ID.
`samplers[].base_url`	string	Base URL clients use to reach the sampler.

Example:

curl --request GET \
  --url https://api.baseten.co/v1/loops/samplers \
  --header "Authorization: Api-Key $BASETEN_API_KEY"

{
  "samplers": [
    {
      "id": "samp_def789",
      "base_url": "https://model-ghi012.api.baseten.co/deployment/dep345/sync"
    }
  ]
}

GET /v1/loops/samplers/

Fetch a Loops sampler by ID. Auth scope: manage_org_training_projects. Path parameters:

Parameter	Type	Description
`sampler_id`	string	Loops sampler ID.

Response body:

Field	Type	Description
`sampler.id`	string	The sampler ID.
`sampler.base_url`	string	Base URL clients use to reach the sampler.

Example:

curl --request GET \
  --url https://api.baseten.co/v1/loops/samplers/samp_def789 \
  --header "Authorization: Api-Key $BASETEN_API_KEY"

{
  "sampler": {
    "id": "samp_def789",
    "base_url": "https://model-ghi012.api.baseten.co/deployment/dep345/sync"
  }
}

GET /v1/loops/checkpoints

List Loops checkpoints filtered by run id, base model, or bt:// URI. Provide exactly one filter. Auth scope: manage_own_user_or_service_account. Query parameters:

Parameter	Type	Required	Description
`run_id`	string	no	Filter by run ID. Returns all checkpoints saved by the run.
`base_model`	string	no	Filter by base model. Returns checkpoints across the caller’s runs of this base model.
`checkpoint_path`	string	no	`bt://` URI of a Loops checkpoint. Form: `bt://loops:<run_id>/(weights\|sampler_weights)/<checkpoint_name>`.

Response body:

Field	Type	Description
`checkpoints`	array	Matching checkpoints.
`checkpoints[].id`	string	The checkpoint ID.
`checkpoints[].run_id`	string	The ID of the run that produced the checkpoint.
`checkpoints[].target`	string	Whether this checkpoint is loadable by the sampler (`sampler`) or by the trainer (`trainer`).
`checkpoints[].checkpoint_id`	string	The checkpoint name.
`checkpoints[].created_at`	string	The timestamp of the checkpoint in ISO 8601 format.
`checkpoints[].checkpoint_type`	string	The type of checkpoint.
`checkpoints[].base_model`	string	The base model of the checkpoint.
`checkpoints[].lora_adapter_config`	object	The adapter config of the checkpoint.
`checkpoints[].size_bytes`	integer	The size of the checkpoint in bytes.
`checkpoints[].sync_status`	string	Sync state of the checkpoint: `SYNCING` or `COMPLETE`.

Example:

curl --request GET \
  --url "https://api.baseten.co/v1/loops/checkpoints?run_id=k4q95w5" \
  --header "Authorization: Api-Key $BASETEN_API_KEY"

{
  "checkpoints": [
    {
      "id": "chkpt_abc123",
      "run_id": "k4q95w5",
      "target": "trainer",
      "checkpoint_id": "step-100",
      "created_at": "2025-05-07T10:00:00Z",
      "checkpoint_type": "lora",
      "base_model": "Qwen/Qwen3-8B",
      "lora_adapter_config": null,
      "size_bytes": 524288000,
      "sync_status": "COMPLETE"
    }
  ]
}

GET /v1/loops/checkpoints//files

Get presigned URLs for the files under a Loops checkpoint. Returns a paginated list. Auth scope: manage_org_training_projects. Path parameters:

Parameter	Type	Description
`checkpoint_id`	string	Loops checkpoint ID.

Query parameters:

Parameter	Type	Required	Description
`page_size`	integer	no	Number of items per page. Defaults to `1000`. Must be a positive integer.
`page_token`	integer	no	Offset token for the next page. Defaults to `0`. Must be non-negative.

Response body:

Field	Type	Description
`presigned_urls`	array	List of presigned URLs for checkpoint files.
`presigned_urls[].url`	string	Presigned download URL.
`presigned_urls[].relative_file_name`	string	File path relative to the checkpoint root.
`presigned_urls[].node_rank`	integer	Rank of the node that wrote this file.
`presigned_urls[].size_bytes`	integer	File size in bytes.
`presigned_urls[].last_modified`	string	Last-modified timestamp.
`next_page_token`	integer	Token to use for the next page. `null` when there are no more results.
`total_count`	integer	Total number of checkpoint files available.

Example:

curl --request GET \
  --url "https://api.baseten.co/v1/loops/checkpoints/chkpt_abc123/files?page_size=50&page_token=0" \
  --header "Authorization: Api-Key $BASETEN_API_KEY"

{
  "presigned_urls": [
    {
      "url": "https://s3.amazonaws.com/...",
      "relative_file_name": "adapter_model.safetensors",
      "node_rank": 0,
      "size_bytes": 524288000,
      "last_modified": "2025-05-07T10:00:00Z"
    }
  ],
  "next_page_token": null,
  "total_count": 1
}

GET /v1/loops/deployments

List the caller’s active Loops deployments. Excludes deployments whose latest status is stopped. Auth scope: manage_org_training_projects. Response body:

Field	Type	Description
`deployments`	array	Active loop deployments.
`deployments[].id`	string	The loop deployment ID.
`deployments[].base_model`	string	The HuggingFace base model the deployment is fine-tuning.
`deployments[].base_url`	string	Base URL clients use to reach the trainer half of the deployment.
`deployments[].status.name`	string	Latest status of the loop deployment.

Example:

curl --request GET \
  --url https://api.baseten.co/v1/loops/deployments \
  --header "Authorization: Api-Key $BASETEN_API_KEY"

{
  "deployments": [
    {
      "id": "dep_def456",
      "base_model": "Qwen/Qwen3-8B",
      "base_url": "https://model-abc123.api.baseten.co/deployment/dep456/sync",
      "status": {
        "name": "RUNNING"
      }
    }
  ]
}

POST /v1/loops/deployments//deactivate

Shut down a Loops deployment by ID. Saved checkpoints remain accessible. Resolving base_model to deployment_id is the caller’s responsibility: list deployments and pick the active one. Auth scope: manage_org_training_projects. Path parameters:

Parameter	Type	Description
`deployment_id`	string	Loops deployment ID.

Response body:

Field	Type	Description
`id`	string	The deactivated loop deployment ID.
`base_model`	string	The base model whose loop deployment was deactivated.
`user.email`	string	Email of the user who owned the loop deployment.

Example:

curl --request POST \
  --url https://api.baseten.co/v1/loops/deployments/dep_def456/deactivate \
  --header "Authorization: Api-Key $BASETEN_API_KEY" \
  --header "Content-Type: application/json"

{
  "id": "dep_def456",
  "base_model": "Qwen/Qwen3-8B",
  "user": {
    "email": "user@example.com"
  }
}

GET /v1/loops/deployments/

Fetch a Loops deployment by ID, including its latest status. Auth scope: manage_org_training_projects. Path parameters:

Parameter	Type	Description
`deployment_id`	string	Loops deployment ID.

Response body:

Field	Type	Description
`deployment.id`	string	The loop deployment ID.
`deployment.base_model`	string	The HuggingFace base model the deployment is fine-tuning.
`deployment.base_url`	string	Base URL clients use to reach the trainer half of the deployment.
`deployment.status.name`	string	Latest status of the loop deployment.

Example:

curl --request GET \
  --url https://api.baseten.co/v1/loops/deployments/dep_def456 \
  --header "Authorization: Api-Key $BASETEN_API_KEY"

{
  "deployment": {
    "id": "dep_def456",
    "base_model": "Qwen/Qwen3-8B",
    "base_url": "https://model-abc123.api.baseten.co/deployment/dep456/sync",
    "status": {
      "name": "RUNNING"
    }
  }
}

Legacy routes

The previous /v1/trainer_sessions/* and /v1/trainers/* paths still work, but new integrations should use the /v1/loops/* paths above.

Method	Path
`POST`	`/v1/trainers/search`
`POST`	`/v1/trainers/checkpoints/search`
`POST`	`/v1/trainer_sessions`
`POST`	`/v1/trainer_sessions/{session_id}/trainers`
`POST`	`/v1/trainer_sessions/{session_id}/samplers`
`GET`	`/v1/trainer_sessions/{session_id}/trainers/{trainer_id}/checkpoints`
`GET`	`/v1/trainer_sessions/{session_id}/trainers/{trainer_id}/checkpoints/{checkpoint_id}/files`

Reference

Inference API

Management API

Training API

Frontier Gateway API

CLI reference

SDK reference

CI/CD

Loops API reference

Routes

POST /v1/loops/sessions

GET /v1/loops/sessions/

POST /v1/loops/runs

GET /v1/loops/runs

GET /v1/loops/runs/

POST /v1/loops/samplers

GET /v1/loops/samplers

GET /v1/loops/samplers/

GET /v1/loops/checkpoints

GET /v1/loops/checkpoints//files

GET /v1/loops/deployments

POST /v1/loops/deployments//deactivate

GET /v1/loops/deployments/

Legacy routes

Reference

Inference API

Management API

Training API

Frontier Gateway API

CLI reference

SDK reference

CI/CD

Documentation Index

​Routes

​POST /v1/loops/sessions

​GET /v1/loops/sessions/

​POST /v1/loops/runs

​GET /v1/loops/runs

​GET /v1/loops/runs/

​POST /v1/loops/samplers

​GET /v1/loops/samplers

​GET /v1/loops/samplers/

​GET /v1/loops/checkpoints

​GET /v1/loops/checkpoints//files

​GET /v1/loops/deployments

​POST /v1/loops/deployments//deactivate

​GET /v1/loops/deployments/

​Legacy routes

Routes

POST /v1/loops/sessions

GET /v1/loops/sessions/

POST /v1/loops/runs

GET /v1/loops/runs

GET /v1/loops/runs/

POST /v1/loops/samplers

GET /v1/loops/samplers

GET /v1/loops/samplers/

GET /v1/loops/checkpoints

GET /v1/loops/checkpoints//files

GET /v1/loops/deployments

POST /v1/loops/deployments//deactivate

GET /v1/loops/deployments/

Legacy routes