Skip to content

Researcher REST API

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:

Endpoint URL for API

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. To find this <CLUSTER-ENDPOINT>, do one of the following:

  • Go to the cluster command-line and run: kubectl get ingress -n runai.
  • In the Administrator user interface, go to Clusters. Each cluster will have a separate URL.


  • By default, researcher APIs are unauthenticated. To protect researcher API (and the researchers themselves), you must configure researcher authentication.
  • Once configured, you must create a Client Application to make API requests.
  • Using the client application and secret, you can call an API to get a time-bound bearer token. You can use the token for subsequent API calls.


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

curl  'https://<CLUSTER-ENDPOINT>/researcher/api/v1/job/team-a' \
  -H 'accept: application/json' \
--header 'Authorization: Bearer <access-token>' 

Researcher API Documentation

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

To review API documentation:

  • Open the Run:AI user interface
  • Go to Clusters
  • Locate your cluster and browse to `https:///researcher/api/docs'.

API documentation is still work-in-progress and will be updated soon.

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.

Last update: January 28, 2022