Get Sub-workspaces

GET

workspace

sub

Get Sub-workspaces

curl --request GET \
  --url https://prod-api.ringg.ai/ca/api/v0/workspace/sub \
  --header 'X-API-KEY: <x-api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<x-api-key>'}};

fetch('https://prod-api.ringg.ai/ca/api/v0/workspace/sub', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://prod-api.ringg.ai/ca/api/v0/workspace/sub",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://prod-api.ringg.ai/ca/api/v0/workspace/sub"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<x-api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://prod-api.ringg.ai/ca/api/v0/workspace/sub")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<x-api-key>'

response = http.request(request)
puts response.read_body

{
  "primary": {
    "id": "2f9a1c44-7e88-4bb1-9a01-5d3c2e7f6a11",
    "name": "Acme Collections HQ",
    "concurrency": 50,
    "limit_concurrency": 50,
    "member_count": 4,
    "billing": {
      "account_type": "postpaid",
      "currency": "INR",
      "credit_limit": 500000,
      "utilized_limit": 12500
    },
    "usage_this_period": 0
  },
  "sub_workspaces": [
    {
      "id": "b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30",
      "name": "Mumbai Collections",
      "created_at": "2026-09-01T06:41:12.884312+00:00",
      "concurrency": 20,
      "limit_concurrency": 20,
      "member_counts": {
        "direct": 2,
        "inherited": 4
      },
      "billing": {
        "account_type": "postpaid",
        "currency": "INR",
        "credit_limit": 200000,
        "utilized_limit": 34210.5
      },
      "usage_this_period": 34210.5
    }
  ],
  "family": {
    "concurrency_capacity": 50,
    "concurrency_allocated": 20,
    "concurrency_available": 30,
    "is_individual_entity": true,
    "credit_limit": 500000,
    "utilized_total": 46710.5,
    "available_total": 453289.5
  }
}

{
  "detail": "Sub-workspaces cannot have their own sub-workspaces."
}

{
  "error": {
    "code": "401 Unauthorized",
    "message": "Invalid credentials"
  }
}

{
  "detail": "Sub-workspaces are not enabled for this workspace."
}

{
  "error": {
    "code": "500 Internal Server Error",
    "message": "An unexpected error occurred on the server."
  }
}

Return the whole family in one call: the primary’s summary, one row per active sub-workspace with its allocation, member counts, and month-to-date usage, and the family totals.

When to use

A tenant dashboard in your own admin tool.
Checking headroom before allocating concurrency or credit.
Reconciling per-client usage at month end.

Reading the response

billing on each row is {account_type, currency, total_available_credits} for prepaid and {account_type, currency, credit_limit, utilized_limit} for postpaid. In a common-billing family the sub-workspace rows carry null limits because charges pool on the primary.
family always has the concurrency keys and is_individual_entity. Postpaid families add credit_limit, utilized_total, and available_total. Prepaid families add available_pot (the primary’s unallocated money) and family_available_total; individual prepaid families also add allocated_balance_total.
usage_this_period is the value of completed calls since the 1st of the current month in the Asia/Kolkata timezone, in the workspace’s billing currency.
limit_concurrency is a sub-workspace’s ceiling: its own allocation in an individual family, the family total in a common family.
Amounts are JSON numbers here.

Integration notes

Authenticate with the primary workspace’s API key.
Works on a primary with no sub-workspaces yet; sub_workspaces is then an empty list.
Archived sub-workspaces are not listed.

Error responses

400: Sub-workspaces cannot have their own sub-workspaces. — the key belongs to a sub-workspace.
401: Invalid or missing API key.
403: Sub-workspaces are not enabled for this workspace.

Example

curl --request GET "https://prod-api.ringg.ai/ca/api/v0/workspace/sub" \
  --header "X-API-KEY: $RINGG_API_KEY"

Headers

X-API-KEY

string

required

(Required) The API key of the PRIMARY workspace. A sub-workspace's key is refused with 400.

Example:

"7251cb4b-3373-43a4-844c-b27a1d45e0c9"

Response

Successful Response: The family overview.

primary

object

Show child attributes

sub_workspaces

object[]

Active sub-workspaces, oldest first.

Show child attributes

family

object

Family totals. Always: the concurrency keys and is_individual_entity. Postpaid families add credit_limit, utilized_total, available_total. Prepaid individual families add available_pot, allocated_balance_total, family_available_total. Prepaid common families add available_pot and family_available_total.

Show child attributes

Get Sub-workspaces

curl --request GET \
  --url https://prod-api.ringg.ai/ca/api/v0/workspace/sub \
  --header 'X-API-KEY: <x-api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<x-api-key>'}};

fetch('https://prod-api.ringg.ai/ca/api/v0/workspace/sub', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://prod-api.ringg.ai/ca/api/v0/workspace/sub",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://prod-api.ringg.ai/ca/api/v0/workspace/sub"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<x-api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://prod-api.ringg.ai/ca/api/v0/workspace/sub")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<x-api-key>'

response = http.request(request)
puts response.read_body

{
  "primary": {
    "id": "2f9a1c44-7e88-4bb1-9a01-5d3c2e7f6a11",
    "name": "Acme Collections HQ",
    "concurrency": 50,
    "limit_concurrency": 50,
    "member_count": 4,
    "billing": {
      "account_type": "postpaid",
      "currency": "INR",
      "credit_limit": 500000,
      "utilized_limit": 12500
    },
    "usage_this_period": 0
  },
  "sub_workspaces": [
    {
      "id": "b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30",
      "name": "Mumbai Collections",
      "created_at": "2026-09-01T06:41:12.884312+00:00",
      "concurrency": 20,
      "limit_concurrency": 20,
      "member_counts": {
        "direct": 2,
        "inherited": 4
      },
      "billing": {
        "account_type": "postpaid",
        "currency": "INR",
        "credit_limit": 200000,
        "utilized_limit": 34210.5
      },
      "usage_this_period": 34210.5
    }
  ],
  "family": {
    "concurrency_capacity": 50,
    "concurrency_allocated": 20,
    "concurrency_available": 30,
    "is_individual_entity": true,
    "credit_limit": 500000,
    "utilized_total": 46710.5,
    "available_total": 453289.5
  }
}

{
  "detail": "Sub-workspaces cannot have their own sub-workspaces."
}

{
  "error": {
    "code": "401 Unauthorized",
    "message": "Invalid credentials"
  }
}

{
  "detail": "Sub-workspaces are not enabled for this workspace."
}

{
  "error": {
    "code": "500 Internal Server Error",
    "message": "An unexpected error occurred on the server."
  }
}

Get Started

API Reference

Webhooks Setup

Telephony Integration

MCP Server

External Integrations

Privacy and Compliance

Get Sub-workspaces

When to use

Reading the response

Integration notes

Error responses

Example

Headers

Response

​When to use

​Reading the response

​Integration notes

​Error responses

​Example

Headers

Response

When to use

Reading the response

Integration notes

Error responses

Example