Skip to content

Researcher REST API


Researcher Kubernetes API is deprecated. See Cluster API for its replacement.

The purpose of the Researcher REST API is to provide an easy-to-use programming interface for submitting, listing, and deleting Jobs.

There are other APIs that provide the same functionality. Specifically:

The Researcher REST API is cluster-specific in the sense that if you have multiple GPU clusters, you will have a separate URL per cluster. This <CLUSTER-ENDPOINT> can be found in the Run:ai User Interface, under Clusters. Each cluster will have a separate URL.


  • By default, researcher APIs are unauthenticated. To protect researcher API, you must configure researcher authentication.
  • Once configured, you must create a Client Application to make API requests. Use the client application and secret, to obtain a time-bound bearer token (<ACCESS-TOKEN>). For details, see Calling REST APIs.
  • Use the token for subsequent API calls.


Get all the jobs for a project named team-a:

curl  'https://<CLUSTER-ENDPOINT>/researcher/api/v1/jobs/team-a' \
  -H 'accept: application/json' \
--header 'Authorization: Bearer <ACCESS-TOKEN>' 

Researcher API Scope

The Researcher API provides the following functionality:

  • Submit a new Job
  • List jobs for specific Projects.
  • Delete an existing Job
  • Get a list of Projects for which you have access to

Researcher API Documentation

To review API documentation:

  • Open the Run:ai user interface
  • Go to Clusters
  • Locate your cluster and browse to https://<cluster-url>/researcher/api/docs.
  • When using the Authenticate button, add Bearer <ACCESS TOKEN> (simply adding the access token will not work).

The document uses the Open API specification to describe the API. You can test the API within the document after creating and saving a token.