Skip to main content
Documentation

REST API

Read projects and runs from scripts and agents.

The Embedl Hub REST API accepts the same personal API keys used by the Python library and CLI. Create a key under Personal API keys on your profile page, then send it as a Bearer token:

curl \
    -H "Authorization: Bearer eh_..." \
    -H "Accept: application/json" \
    https://hub.embedl.com/api/projects

Successful responses are returned as JSON with a top-level data field. Errors are returned with a top-level errors field.

List runs

List runs in a project:

curl \
    -H "Authorization: Bearer eh_..." \
    "https://hub.embedl.com/api/projects/<project-id>/runs?limit=100&offset=0"

The response contains:

  • data.items: run summaries with id, name, type, customType, description, status, parentRunId, createdAt, startedAt, and endedAt
  • data.pagination.limit: the page size used for the request
  • data.pagination.offset: the starting offset used for the request
  • data.pagination.total: total matching runs
  • data.pagination.hasMore: whether another page is available
  • data.pagination.nextOffset: the next offset to request, or null

limit defaults to 100 and can be at most 500. offset defaults to 0. Runs are sorted newest first by createdAt, then by id.

To fetch all pages, repeat the request with offset set to nextOffset until hasMore is false.

Filters

Filters are comma-separated:

curl \
    -H "Authorization: Bearer eh_..." \
    "https://hub.embedl.com/api/projects/<project-id>/runs?status=FINISHED,FAILED&type=PROFILE,CUSTOM&customType=experiment"

Available filters:

  • status: RUNNING, SCHEDULED, FINISHED, FAILED, KILLED
  • type: COMPILE, PROFILE, EVAL, INFERENCE, GRAPH, CUSTOM
  • customType: custom labels for CUSTOM runs

Read one run

Read a run summary:

curl \
    -H "Authorization: Bearer eh_..." \
    https://hub.embedl.com/api/projects/<project-id>/runs/<run-id>

To include all logged attributes for the run, use include=all:

curl \
    -H "Authorization: Bearer eh_..." \
    "https://hub.embedl.com/api/projects/<project-id>/runs/<run-id>?include=all"

You can also request specific attributes:

?include=metrics,params,tags,externalLinks,artifacts

external-links is accepted as an alias for externalLinks.

When artifacts are included, use the artifact ID with /api/artifacts/<artifact-id>/download to download the file.

Create and update descriptions

Pass an optional description when creating a run:

curl -X POST \
    -H "Authorization: Bearer eh_..." \
    -H "Content-Type: application/json" \
    -d '{"type":"COMPILE","description":"Baseline before quantization"}' \
    https://hub.embedl.com/api/projects/<project-id>/runs

Update or clear the description with PATCH:

curl -X PATCH \
    -H "Authorization: Bearer eh_..." \
    -H "Content-Type: application/json" \
    -d '{"description":null}' \
    https://hub.embedl.com/api/projects/<project-id>/runs/<run-id>

Descriptions are trimmed, limited to 1,000 characters, and returned on run create, detail, and list responses. Blank or whitespace-only descriptions are stored as null.

Read run attributes

Each run attribute collection is also available as a separate endpoint:

GET /api/projects/<project-id>/runs/<run-id>/metrics
GET /api/projects/<project-id>/runs/<run-id>/params
GET /api/projects/<project-id>/runs/<run-id>/tags
GET /api/projects/<project-id>/runs/<run-id>/external-links
GET /api/projects/<project-id>/runs/<run-id>/artifacts

These endpoints return all values for the run. Attribute collections are not paginated.

Status codes

  • 200: request succeeded
  • 201: run created
  • 204: run updated
  • 401: missing, malformed, invalid, revoked, or expired API key
  • 400: request body validation failed
  • 404: project or run was not found, including resources you cannot access
  • 422: query parameter validation failed