Runners

Soda Cloud API Runner Endpoints

List runners

get

https://cloud.soda.iohttps://cloud.us.soda.io

/api/v1/runners

This endpoint allows you to list runners in your organization.

This GET is a paginated API that uses the following parameters to request specific details:

• size: Supply an integer value between 10 and 1000, inclusive. The default value is 10.

• page: Supply an integer value. The default value is 0.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Any Soda Cloud user in your organization may execute this query.

Tags

Runners

Rate limiting

60 requests/60 seconds

Authorizations

basicAuthApiKey

AuthorizationstringRequired

Query parameters

pageinteger · int32Optional

sizeinteger · int32Optional

Responses

200

Successful response

application/json

firstbooleanRequired

lastbooleanRequired

numberinteger · int32Required

sizeinteger · int32Required

totalElementsinteger · int32Required

totalPagesinteger · int32Required

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

429

Too many requests

application/json

500

Internal server error

application/json

get

/api/v1/runners

HTTPcURLJavaScriptPython

GET /api/v1/runners HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "content": [
    {
      "id": "text",
      "isOnline": true,
      "label": "text",
      "lastSeenTimestamp": "text",
      "name": "text",
      "type": "SELF_HOSTED",
      "versions": {
        "agent": "text",
        "library": "text"
      }
    }
  ],
  "first": true,
  "last": true,
  "number": 1,
  "size": 1,
  "totalElements": 1,
  "totalPages": 1
}

Create a soda runner

post

https://cloud.soda.iohttps://cloud.us.soda.io

/api/v1/runners

Creates an API key for a new self-hosted runner deployment.

Returns the API key credentials (id and secret) to configure the runner. The credentials are only returned at creation time and cannot be retrieved later, so make sure to store them securely.

After creation the runner does not immediately become visible in Soda Cloud. The runner needs to registers itself using the API key credentials before it becomes available.

See deployment instructions for setting up the runner.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Runners

Rate limiting

10 requests/60 seconds

Authorizations

basicAuthApiKey

AuthorizationstringRequired

Responses

200

Successful response

application/json

apiKeyIdstringOptional

apiKeySecretstringOptional

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

429

Too many requests

application/json

500

Internal server error

application/json

post

/api/v1/runners

HTTPcURLJavaScriptPython

POST /api/v1/runners HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "apiKeyId": "text",
  "apiKeySecret": "text"
}

Get a runner

get

https://cloud.soda.iohttps://cloud.us.soda.io

/api/v1/runners/{runnerId}

This endpoint allows you to retrieve a specific runner by its ID.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Any Soda Cloud user in your organization may execute this query.

Tags

Runners

Rate limiting

1000 requests/60 seconds

Authorizations

basicAuthApiKey

AuthorizationstringRequired

Path parameters

runnerIdstringRequired

Responses

200

Successful response

application/json

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

get

/api/v1/runners/{runnerId}

HTTPcURLJavaScriptPython

GET /api/v1/runners/{runnerId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "runner": {
    "id": "text",
    "isOnline": true,
    "label": "text",
    "lastSeenTimestamp": "text",
    "name": "text",
    "type": "SELF_HOSTED",
    "versions": {
      "agent": "text",
      "library": "text"
    }
  }
}

Delete a runner

delete

https://cloud.soda.iohttps://cloud.us.soda.io

/api/v1/runners/{runnerId}

This endpoint allows you to delete a specific self-hosted runner by its ID. If the runner is still in use, the request will fail with a 400 Bad Request response.

Soda-hosted and virtual runners cannot be deleted through this endpoint.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Runners

Rate limiting

10 requests/60 seconds

Authorizations

basicAuthApiKey

AuthorizationstringRequired

Path parameters

runnerIdstringRequired

Responses

200

Successful response

application/json

objectOptional

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

delete

/api/v1/runners/{runnerId}

HTTPcURLJavaScriptPython

DELETE /api/v1/runners/{runnerId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{}