usage

Spend: noclick.usage(group_by="user"), noclick.Usage.series(group_by="agent"), noclick.Usage.limits().

noclick.usage(
    period='month', *, group_by=None, agent=None, user=..., client=None
) -> Usage

Spend for period ("month"), optionally split group_by "user", "key", "agent" or "project" (each app), and narrowed to one agent (an Agent or its id). Needs the usage scope.

Parameters

periodstrdefault 'month'

group_bystr | Nonedefault None

agentAnydefault None

userAny

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)

clientClient | None

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

(default None)

Returns

Usage

The period's total_usd and, with group_by, one group per user, key, agent or app that spent, largest first. Without group_by, groups is empty.

Usage

See this month's spend per user:

month = noclick.usage(group_by="user")
print(month.total_usd)
for group in month.groups:
    print(group.id, group.usd, group.events)

Inside as_user, it covers only that user:

with noclick.as_user("user_42"):
    print(noclick.usage().total_usd)

What one agent cost this month, per user it talked to:

support = noclick.Agent.from_name("support")
by_user = noclick.usage(group_by="user", agent=support)
print(by_user.total_usd, by_user["user_42"].usd)

What each app spent, to bill its user on:

booking = noclick.Project.from_name("booking", user="user_42")
by_app = noclick.usage(group_by="project")
print(by_app[booking.id].usd)

Usage

class Usage

What the account (or the current user) spent in period.

Attributes

period	Any
total_usd	float
groups	list[UsageGroup]
raw	dict[str, Any]	The response JSON exactly as the API sent it.

getitem

usage[group_id] -> UsageGroup

The spend of one user, key, agent or app id in a grouped usage (None is the account's own).

Parameters

group_idstr | Nonerequired

Returns

UsageGroup

That id's spend and event count; an id that spent nothing reads as $0 with no events.

Usage

user = noclick.User.from_id("user_42")
month = noclick.usage(group_by="user")
print(month[user.id].usd)   # 0.0 for a user who spent nothing

get

usage.get(group_id, default=None) -> Any

The group of an id that spent something in a grouped usage, else default.

Parameters

group_idstr | Nonerequired

defaultAnydefault None

Returns

Any

The UsageGroup, or default when the id spent nothing in the period.

Usage

support = noclick.Agent.from_name("support")
month = noclick.usage(group_by="agent")
if month.get(support.id) is None:
    print("support has cost nothing this month")

seriesstaticasync

noclick.Usage.series(
    *, from_=None, to=None, interval=None, group_by=None, key=None, agent=None,
    user_filter=None, user=..., client=None
) -> UsageSeries

Daily spend between from_ and to (default: the current month, at most 92 days), one line per group_by key, user, agent, type or project (an app). key is a key id or prefix.

Parameters

from_Anydefault None

toAnydefault None

intervalstr | Nonedefault None

group_bystr | Nonedefault None

keystr | Nonedefault None

agentAnydefault None

user_filterAny

Which users a read covers: noclick.ALL_USERS, noclick.NO_USER, a User, or your id for one. It filters without acting as that user.

(default None)

userAny

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)

clientClient | None

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

(default None)

Returns

UsageSeries

The lines, largest first, each with its label, total_usd and daily points. A day with no spend has no point.

Usage

Chart this month's spend by what it was for:

series = noclick.Usage.series(group_by="type")
for line in series.series:
    print(line.label, line.total_usd, [point.usd for point in line.points])

Or one agent's last 30 days, one line per user:

from datetime import datetime, timedelta, timezone

support = noclick.Agent.from_name("support")
now = datetime.now(timezone.utc)
series = noclick.Usage.series(from_=now - timedelta(days=30), to=now, group_by="user", agent=support)

limitsstaticasync

noclick.Usage.limits(*, client=None) -> UsageLimits

This month's spend of every capped key, user and agent (account principals), and of every app with a budget.

Parameters

clientClient | None

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

(default None)

Returns

UsageLimits

Each capped key and user with its cap and spent, each budgeted agent with its budget, spent and subtree_spent, each budgeted app (projects) with its budget and spent, and when the caps reset (resets_at).

Usage

limits = noclick.Usage.limits()
for cap in limits.users:
    print(cap.id, cap.spent, cap.cap)
for app in limits.projects:
    print(app.name, app.user_id, app.spent, app.budget)
print(limits.resets_at)

UsageGroup

class UsageGroup

Spend of one user, key, agent or app (id) in the period.

Attributes

id	str \| None
usd	float
events	int
raw	dict[str, Any]	The response JSON exactly as the API sent it.

UsageSeries

class UsageSeries

Attributes

interval	str
from_	Any
to	Any
total_usd	float
series	list[UsageSeriesLine]
raw	dict[str, Any]	The response JSON exactly as the API sent it.

UsageSeriesLine

class UsageSeriesLine

One key, user, agent or usage type's spend over the period. label is a key name (Console for the console key), your id for a user, an agent name or a type label.

Attributes

id	str \| None
label	str \| None
total_usd	float
events	int
points	list[UsagePoint]
raw	dict[str, Any]	The response JSON exactly as the API sent it.

UsagePoint

class UsagePoint

Spend in one interval starting at t.

Attributes

t	Any
usd	float
events	int

UsageLimits

class UsageLimits

Every capped key, user and agent with this month's spend, and every app with a budget.

Attributes

period_start	Any
resets_at	Any
keys	list[KeyCap]
users	list[UserCap]
agents	list[AgentBudget]
projects	list[ProjectBudget]	Each app with a `budget_usd_per_month`.
raw	dict[str, Any]	The response JSON exactly as the API sent it.

KeyCap

class KeyCap

A capped key's spend this month.

Attributes

id	str
name	str \| None
cap	float \| None
spent	float
raw	dict[str, Any]	The response JSON exactly as the API sent it.

UserCap

class UserCap

A capped user's spend this month; id is your id for the user.

Attributes

id	str
cap	float \| None
spent	float
raw	dict[str, Any]	The response JSON exactly as the API sent it.

AgentBudget

class AgentBudget

A budgeted agent's spend this month; subtree_spent adds the agents it spawned.

Attributes

id	str
name	str \| None
budget	float \| None
spent	float
subtree_spent	float
raw	dict[str, Any]	The response JSON exactly as the API sent it.

ProjectBudget

class ProjectBudget

A budgeted app's spend this month: id and name are the app's, user_id the user it belongs to (None for your account's own).

Attributes

id	str
name	str \| None
user_id	str \| None
budget	float \| None
spent	float
raw	dict[str, Any]	The response JSON exactly as the API sent it.