Sessions

Create a session

Body Parameters (application/json)

Name, Type	Description
One of

HTTP Response Status Codes

Status code	Description
200	Ok
400	Bad Request
401	Unauthorized
500	Internal error

Code samples

POST

/v1/sessions

curl -X POST \
  /api/v1/sessions \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

import requests
 
response = requests.request(
    "POST",
    "/api/v1/sessions",
    headers={
      "Accept": "application/json",
      "IBM-API-Version": "2025-05-01",
      "Authorization": "Bearer YOUR-TOKEN",
      "Service-CRN": "YOUR-SERVICE-CRN"
    },
)
print(response.json())

Responses

Status code

{
  "id": "example",
  "backend_name": "example",
  "started_at": "example",
  "activated_at": "example",
  "closed_at": "example",
  "last_job_started": "example",
  "last_job_completed": "example",
  "interactive_ttl": 1,
  "max_ttl": 1,
  "active_ttl": 1,
  "state": "open",
  "state_reason": "example",
  "accepting_jobs": true,
  "mode": "batch",
  "timestamps": [
    {
      "status": "open",
      "timestamp": "example"
    }
  ],
  "user_id": "example",
  "elapsed_time": 1.432
}

Status code

{
  "type": "object",
  "description": "Job session",
  "properties": {
    "id": {
      "type": "string",
      "description": "Job ID"
    },
    "backend_name": {
      "type": "string",
      "description": "Backend name. May not be set when in the \"open\" state.",
      "nullable": true
    },
    "started_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of when the session was started"
    },
    "activated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of when the session state was changed to active"
    },
    "closed_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of when the session was closed"
    },
    "last_job_started": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of when the last job in the session started"
    },
    "last_job_completed": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of when the last job in the session completed"
    },
    "interactive_ttl": {
      "type": "integer",
      "description": "The maximum time (in seconds) between jobs to keep the session active"
    },
    "max_ttl": {
      "type": "integer",
      "description": "The maximum time (in seconds) for session to run, subject to plan limits"
    },
    "active_ttl": {
      "type": "integer",
      "description": "The remaining time (in seconds) for the session to be in the active state while jobs are running."
    },
    "state": {
      "type": "string",
      "enum": [
        "open",
        "active",
        "inactive",
        "closed"
      ],
      "description": "The state of the session.\n- open: The session is waiting to run jobs.\n- active: The session has priority to run jobs on the backend and is running jobs or is waiting for more jobs to run.\n- inactive: The session does not have priority and is not running any jobs.\n- closed: The session is not running any jobs and will not accept/run new jobs.\n"
    },
    "state_reason": {
      "type": "string",
      "description": "The reason for the state change."
    },
    "accepting_jobs": {
      "type": "boolean",
      "description": "If true, the session is actively accepting new jobs to be queued. If false, jobs will be rejected on create and the session will be immediately closed when there are no more jobs to run in the session."
    },
    "mode": {
      "type": "string",
      "description": "Execution mode to run the session in",
      "enum": [
        "batch",
        "dedicated"
      ]
    },
    "timestamps": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Contains information about the time a specific status transition happened",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "open",
              "active",
              "inactive",
              "closed"
            ],
            "description": "The state of the session.\n- open: The session is waiting to run jobs.\n- active: The session has priority to run jobs on the backend and is running jobs or is waiting for more jobs to run.\n- inactive: The session does not have priority and is not running any jobs.\n- closed: The session is not running any jobs and will not accept/run new jobs.\n"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of when the session transitioned into the given status"
          }
        },
        "required": [
          "status",
          "timestamp"
        ]
      }
    },
    "user_id": {
      "type": "string",
      "description": "The id of the user who created the session."
    },
    "elapsed_time": {
      "type": "number",
      "description": "Usage in seconds. Can be null for ongoing sessions.",
      "example": 1.432
    }
  },
  "required": [
    "id",
    "backend_name",
    "mode"
  ]
}

Get a session

Path Parameters

Name, Type	Description
id Required string	Job Session ID

HTTP Response Status Codes

Status code	Description
200	OK
401	Unauthorized
404	Not Found
500	Internal error

Code samples

GET

/v1/sessions/{id}

curl -X GET \
  /api/v1/sessions/{id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

import requests
 
response = requests.request(
    "GET",
    "/api/v1/sessions/{id}",
    headers={
      "Accept": "application/json",
      "IBM-API-Version": "2025-05-01",
      "Authorization": "Bearer YOUR-TOKEN",
      "Service-CRN": "YOUR-SERVICE-CRN"
    },
)
print(response.json())

Responses

Status code

{
  "id": "example",
  "backend_name": "example",
  "started_at": "example",
  "activated_at": "example",
  "closed_at": "example",
  "last_job_started": "example",
  "last_job_completed": "example",
  "interactive_ttl": 1,
  "max_ttl": 1,
  "active_ttl": 1,
  "state": "open",
  "state_reason": "example",
  "accepting_jobs": true,
  "mode": "batch",
  "timestamps": [
    {
      "status": "open",
      "timestamp": "example"
    }
  ],
  "user_id": "example",
  "elapsed_time": 1.432
}

Status code

{
  "type": "object",
  "description": "Job session",
  "properties": {
    "id": {
      "type": "string",
      "description": "Job ID"
    },
    "backend_name": {
      "type": "string",
      "description": "Backend name. May not be set when in the \"open\" state.",
      "nullable": true
    },
    "started_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of when the session was started"
    },
    "activated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of when the session state was changed to active"
    },
    "closed_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of when the session was closed"
    },
    "last_job_started": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of when the last job in the session started"
    },
    "last_job_completed": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of when the last job in the session completed"
    },
    "interactive_ttl": {
      "type": "integer",
      "description": "The maximum time (in seconds) between jobs to keep the session active"
    },
    "max_ttl": {
      "type": "integer",
      "description": "The maximum time (in seconds) for session to run, subject to plan limits"
    },
    "active_ttl": {
      "type": "integer",
      "description": "The remaining time (in seconds) for the session to be in the active state while jobs are running."
    },
    "state": {
      "type": "string",
      "enum": [
        "open",
        "active",
        "inactive",
        "closed"
      ],
      "description": "The state of the session.\n- open: The session is waiting to run jobs.\n- active: The session has priority to run jobs on the backend and is running jobs or is waiting for more jobs to run.\n- inactive: The session does not have priority and is not running any jobs.\n- closed: The session is not running any jobs and will not accept/run new jobs.\n"
    },
    "state_reason": {
      "type": "string",
      "description": "The reason for the state change."
    },
    "accepting_jobs": {
      "type": "boolean",
      "description": "If true, the session is actively accepting new jobs to be queued. If false, jobs will be rejected on create and the session will be immediately closed when there are no more jobs to run in the session."
    },
    "mode": {
      "type": "string",
      "description": "Execution mode to run the session in",
      "enum": [
        "batch",
        "dedicated"
      ]
    },
    "timestamps": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Contains information about the time a specific status transition happened",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "open",
              "active",
              "inactive",
              "closed"
            ],
            "description": "The state of the session.\n- open: The session is waiting to run jobs.\n- active: The session has priority to run jobs on the backend and is running jobs or is waiting for more jobs to run.\n- inactive: The session does not have priority and is not running any jobs.\n- closed: The session is not running any jobs and will not accept/run new jobs.\n"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of when the session transitioned into the given status"
          }
        },
        "required": [
          "status",
          "timestamp"
        ]
      }
    },
    "user_id": {
      "type": "string",
      "description": "The id of the user who created the session."
    },
    "elapsed_time": {
      "type": "number",
      "description": "Usage in seconds. Can be null for ongoing sessions.",
      "example": 1.432
    }
  },
  "required": [
    "id",
    "backend_name",
    "mode"
  ]
}

Update a session

Path Parameters

Name, Type	Description
id Required string	Job Session ID

Body Parameters (application/json)

Name, Type	Description
accepting_jobs Required boolean	If true, the session is actively accepting new jobs to be queued. If false, jobs will be rejected on create and the session will be immediately closed when there are no more jobs to run in the session.

HTTP Response Status Codes

Status code	Description
204	Successfully updated session
401	Unauthorized
404	Not Found
500	Internal error

Code samples

PATCH

/v1/sessions/{id}

curl -X PATCH \
  /api/v1/sessions/{id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01' \
  -H 'Content-Type: application/json' \
  -d '{"accepting_jobs":true}'

import requests
 
response = requests.request(
    "PATCH",
    "/api/v1/sessions/{id}",
    headers={
        "Accept": "application/json",
        "IBM-API-Version": "2025-05-01",
        "Authorization": "Bearer YOUR-TOKEN",
        "Service-CRN": "YOUR-SERVICE-CRN",
        "Content-Type": "application/json"
    },
    data="{\"accepting_jobs\":true}"
)
print(response.json())

Responses

Status code

Successfully updated session

Close job session

Closes the runtime session. The session stops accepting new jobs and queued jobs will not run. Existing running jobs will run to completion. This is analogous to the cancel() function in Qiskit.

Path Parameters

Name, Type	Description
id Required string	Session Id

HTTP Response Status Codes

Status code	Description
204	Successfully closed runtime session

Code samples

DELETE

/v1/sessions/{id}/close

curl -X DELETE \
  /api/v1/sessions/{id}/close \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

import requests
 
response = requests.request(
    "DELETE",
    "/api/v1/sessions/{id}/close",
    headers={
      "Accept": "application/json",
      "IBM-API-Version": "2025-05-01",
      "Authorization": "Bearer YOUR-TOKEN",
      "Service-CRN": "YOUR-SERVICE-CRN"
    },
)
print(response.json())

Responses

Status code

Successfully closed runtime session