FruxonDocs
ApiKnowledge bases

Gets the knowledge base's searches and retrieved tokens bucketed over time.

A search is one `search_assets` call by an agent whose scope included this base; a search that returned nothing from it still counts (`emptySearches`). Retrieved tokens are the returned passages' text as the search index counts it. Each search is counted in the bucket it was made in; buckets with none are omitted. Searches are recorded from 15 October 2026 and kept 90 days at most, and no longer than the workspace keeps its runs, so a window reaching further back is counted from `countedFromMs`. Up to 20 searching agents you can open are named; the rest are counted in `otherAgents`. Two money figures cover the same counted window. `upkeepUsd` is what the base itself cost: the runs of the agents it owns (consolidator, editor, its sources' pipeline agents) and the embeddings of its publishes, itemized in `upkeep`. `costToServeUsd` is an estimate, not a bill: each search's retrieved tokens priced once at the input price of its run's dominant model that day. That spend is already on the searching agents' own costs, so the two are never added together.

GET
/v1/tenants/{tenant}/knowledgeBases/{knowledgeBase}/usage

Authorization

Bearer
AuthorizationBearer <token>

JWT Authorization header using the Bearer scheme. Enter 'Bearer' [space] and then your token.

In: header

Path Parameters

knowledgeBase*string

The knowledge base id.

Formatuuid
tenant*string

The tenant identifier

Query Parameters

interval?string

Bucket granularity (hour, day, week). Defaults to day.

Default"DAY"
Value in"UNSPECIFIED" | "HOUR" | "DAY" | "WEEK"
from?integer

Window start as Unix milliseconds (inclusive). Defaults to 30 days before to.

Formatint64
to?integer

Window end as Unix milliseconds (exclusive). Defaults to now.

Formatint64
origin?string

Which runs to count: PRODUCTION (the default) or TEST.

Default"PRODUCTION"
Value in"UNSPECIFIED" | "PRODUCTION" | "TEST"

Response Body

curl -X GET "https://api.fruxon.com/v1/tenants/string/knowledgeBases/497f6eca-6276-4993-bfeb-53cbbbba6f08/usage"
{
  "knowledgeBaseId": "00000000-0000-0000-0000-000000000000",
  "interval": "HOUR",
  "origin": "PRODUCTION",
  "window": {
    "fromMs": 0,
    "toMs": 0
  },
  "countedFromMs": 0,
  "totals": {
    "searches": 0,
    "emptySearches": 0,
    "notFullySearched": 0,
    "emptyNotFullySearched": 0,
    "documentScoped": 0,
    "passages": 0,
    "retrievedTokens": 0,
    "phrasings": 0,
    "upkeepUsd": 0,
    "costToServeUsd": 0,
    "costToServeUnpricedSearches": 0
  },
  "points": [
    {
      "bucketStartMs": 0,
      "searches": 0,
      "retrievedTokens": 0,
      "emptySearches": 0,
      "upkeepUsd": 0,
      "costToServeUsd": 0
    }
  ],
  "agents": [
    {
      "agentId": "string",
      "displayName": "string",
      "searches": 0,
      "retrievedTokens": 0
    }
  ],
  "otherAgents": {
    "count": 0,
    "searches": 0
  },
  "upkeep": {
    "agents": [
      {
        "agentId": "string",
        "role": "UNSPECIFIED",
        "runs": 0,
        "costUsd": 0
      }
    ],
    "embedding": {
      "publishes": 0,
      "tokens": 0,
      "costUsd": 0
    }
  }
}
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}
Empty
Empty
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}