Skip to main content
Documentation
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, 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

external-links is accepted as an alias for externalLinks.

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

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

Status codes

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