Get your Noesis usage

GET/v1/detect/usage

Product: Noesis (call intelligence). URL: https://api.noesis.detectif.ai/v1/detect/usage.

Your Noesis calls and call minutes over the last days days (default 30): how many calls and file analyses, seconds of audio, billed minutes and what was charged, and how many run right now. Requires scope noesis:read.

Authentication

Send your API key as Authorization: Bearer <your API key>.

Headers

Name	Type	Details
`Authorization`required	string	`Bearer <your API key>`. Keys are created in the dashboard; see Authentication.

Query parameters

Name	Type	Details
`days`optional	integer	Length of the period in days, ending now (1-90). 1 to 90default `30`

Response

200 Success.

request_idstringrequired
objectstringrequired
always "noesis.usage"
daysintegerrequired
periodobjectrequired
callsintegerrequired
Calls and file analyses started in the period.
calls_usedintegerrequired
Same as calls (kept for older clients).
streamsintegerrequired
filesintegerrequired
audio_secondsnumberrequired
billed_secondsnumberrequired
minutesnumberrequired
Billed call minutes (billed_seconds / 60).
credits_chargedinteger or null
What the calls used from your balance.
active_sessionsintegerrequired
concurrent_limitintegerrequired
How many calls or file analyses may run at the same time.
planstringrequired
One of: free, unlimited
unlimitedbooleanrequired

Example response

JSON

{
  "request_id": "req_8f14e45fceea167a5a36dedd",
  "object": "noesis.usage",
  "days": 30,
  "period": {
    "start": "2026-09-19T09:30:00Z",
    "end": "2026-10-19T09:30:00Z"
  },
  "calls": 12,
  "calls_used": 12,
  "streams": 10,
  "files": 2,
  "audio_seconds": 1284.5,
  "billed_seconds": 1280,
  "minutes": 21.33,
  "active_sessions": 1,
  "concurrent_limit": 2,
  "plan": "free",
  "unlimited": false
}

Errors

Status	Meaning
400	The request is invalid, for example an API key in the URL or an unsupported parameter.
401	The API key is missing, invalid or revoked.
403	The key lacks the required scope, the e-mail address is not verified, or the account is suspended.
429	Too many requests, or too many calls and file analyses at the same time. Wait for Retry-After seconds.
500	Something went wrong on our side.

Error bodies share one shape with a stable error.code; see Errors for every code and how to fix it.

Code samples

cURL

curl "https://api.noesis.detectif.ai/v1/detect/usage" \
  -H "Authorization: Bearer $DETECTIF_API_KEY"

Python

import os

import requests

resp = requests.get(
    "https://api.noesis.detectif.ai/v1/detect/usage",
    headers={"Authorization": f"Bearer {os.environ['DETECTIF_API_KEY']}"},
    timeout=30,
)
print(resp.status_code, resp.json())

JavaScript

const res = await fetch("https://api.noesis.detectif.ai/v1/detect/usage", {
  headers: {
    Authorization: `Bearer ${process.env.DETECTIF_API_KEY}`,
  },
});
console.log(res.status, await res.json());

#Authentication

#Headers

#Query parameters

#Response

#Example response

#Errors

#Code samples