Read individual entity groups' AI credit usage

curl --request POST \
  --url https://{instance}.omniapp.co/api/v1/ai/credit-usage/entity-groups \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entities": [
    "blobsrus"
  ],
  "period": "2026-09"
}
'

import requests

url = "https://{instance}.omniapp.co/api/v1/ai/credit-usage/entity-groups"

payload = {
    "entities": ["blobsrus"],
    "period": "2026-09"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({entities: ['blobsrus'], period: '2026-09'})
};

fetch('https://{instance}.omniapp.co/api/v1/ai/credit-usage/entity-groups', 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://{instance}.omniapp.co/api/v1/ai/credit-usage/entity-groups",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'entities' => [
        'blobsrus'
    ],
    'period' => '2026-09'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://{instance}.omniapp.co/api/v1/ai/credit-usage/entity-groups"

	payload := strings.NewReader("{\n  \"entities\": [\n    \"blobsrus\"\n  ],\n  \"period\": \"2026-09\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{instance}.omniapp.co/api/v1/ai/credit-usage/entity-groups")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entities\": [\n    \"blobsrus\"\n  ],\n  \"period\": \"2026-09\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{instance}.omniapp.co/api/v1/ai/credit-usage/entity-groups")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entities\": [\n    \"blobsrus\"\n  ],\n  \"period\": \"2026-09\"\n}"

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

{
  "periodEnd": 1790812800000,
  "periodStart": 1788220800000,
  "entityGroups": [
    {
      "creditsUsed": 42,
      "entity": "blobsrus"
    }
  ]
}

{
  "detail": "<string>",
  "status": 400
}

{
  "detail": "Unauthorized: Missing or invalid API key",
  "status": 401
}

{
  "detail": "<string>",
  "status": 403
}

{
  "detail": "<string>",
  "status": 404
}

Credit Usage

Read individual entity groups' AI credit usage

Organization Admin permissions are required to use this endpoint.

List individual embed entity groups’ (up to 1,000 unique entities per request) AI credit usage for one billing period: the current UTC calendar month by default, or an earlier month named by the period field. Each included entity must have an entity group in the organization at the time of the request. Unknown, invalid, and duplicate entity values will fail the request.

Returns each entity group’s credits used, in request order, plus the bounds of the period read. Entity groups with no usage in that period will report 0.

POST

credit-usage

entity-groups

Read individual entity groups' AI credit usage

curl --request POST \
  --url https://{instance}.omniapp.co/api/v1/ai/credit-usage/entity-groups \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entities": [
    "blobsrus"
  ],
  "period": "2026-09"
}
'

import requests

url = "https://{instance}.omniapp.co/api/v1/ai/credit-usage/entity-groups"

payload = {
    "entities": ["blobsrus"],
    "period": "2026-09"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({entities: ['blobsrus'], period: '2026-09'})
};

fetch('https://{instance}.omniapp.co/api/v1/ai/credit-usage/entity-groups', 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://{instance}.omniapp.co/api/v1/ai/credit-usage/entity-groups",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'entities' => [
        'blobsrus'
    ],
    'period' => '2026-09'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://{instance}.omniapp.co/api/v1/ai/credit-usage/entity-groups"

	payload := strings.NewReader("{\n  \"entities\": [\n    \"blobsrus\"\n  ],\n  \"period\": \"2026-09\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{instance}.omniapp.co/api/v1/ai/credit-usage/entity-groups")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entities\": [\n    \"blobsrus\"\n  ],\n  \"period\": \"2026-09\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{instance}.omniapp.co/api/v1/ai/credit-usage/entity-groups")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entities\": [\n    \"blobsrus\"\n  ],\n  \"period\": \"2026-09\"\n}"

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

{
  "periodEnd": 1790812800000,
  "periodStart": 1788220800000,
  "entityGroups": [
    {
      "creditsUsed": 42,
      "entity": "blobsrus"
    }
  ]
}

{
  "detail": "<string>",
  "status": 400
}

{
  "detail": "Unauthorized: Missing or invalid API key",
  "status": 401
}

{
  "detail": "<string>",
  "status": 403
}

{
  "detail": "<string>",
  "status": 404
}

An entity whose group has since been deleted 404s for every month, including months when the group still existed, because the entity must have an entity group in the organization right now. Its usage rows aren’t deleted.

Authorizations

Authorization

string

header

required

Can be either an Organization API Key or Personal Access Token (PAT).

Include in the Authorization header as: Bearer YOUR_TOKEN

Body

application/json

entities

string[]

required

Entity groups to read usage for, at most 1000 per request. Each entry is an embed entity (the SSO entity value) corresponding to an entity group that exists in the organization right now, even when reading a past month. Each entity must be included only once, as duplicated entries will fail the request.

Required array length: 1 - 1000 elements

period

string

UTC calendar month to read, as YYYY-MM, from 2000-01 to 2099-12. Omit it to read the current billing period. A month after the current one is rejected; a month before AI credit metering began reports 0 for every entity.

Pattern: ^20\d{2}-(0[1-9]|1[0-2])$

Example:

"2026-09"

Response

Each requested entity group's credit usage for the billing period read, in request order.

periodEnd

integer

required

Start of the month after the billing period read, as a Unix ms timestamp (UTC calendar-month boundary, exclusive).

Required range: x >= 0

Example:

1790812800000

periodStart

integer

required

Start of the billing period read, as a Unix ms timestamp (UTC calendar-month boundary).

Required range: x >= 0

Example:

1788220800000

entityGroups

object[]

required

Show child attributes

Getting started

Who am I?

Administration APIs

AI APIs

App APIs

Branch APIs

Connection APIs

Content APIs

Dashboard APIs

Document APIs

Embed APIs

Folder APIs

Label APIs

Model APIs

Query APIs

Schedule APIs

Upload APIs

User APIs

User group APIs

Read individual entity groups' AI credit usage

Authorizations

Body

Response