Metering & schedules
Compute accounting and recurring work. MeteringService reports what this instance can say
about usage and manages the tenant’s self-managed CU budget. SchedulesService keeps
the recurring fetches that the FACE app shows as Briefs (Fetch section). In the protos a
brief is a Schedule.
Summary
| Service | RPC | Kind | Purpose |
|---|---|---|---|
| MeteringService | GetResourceUsage | Unary | What is and is not measured for the caller’s tenant |
| MeteringService | GetComputeBudget | Unary | Read the self-managed CU budget |
| MeteringService | SetComputeBudget | Unary | Set the self-managed CU budget to an absolute value |
| SchedulesService | ListSchedules | Unary | List schedules |
| SchedulesService | CreateSchedule | Unary | Create an active schedule |
| SchedulesService | UpdateSchedule | Unary | Replace a schedule’s title, description and frequency |
| SchedulesService | SetScheduleActive | Unary | Pause or resume a schedule |
| SchedulesService | DeleteSchedule | Unary | Delete a schedule |
MeteringService
Full name semantics.v1.MeteringService.
Scope. Every figure belongs to the caller’s tenant, taken from the verified session. The
instance_id in these requests is accepted but not used to choose what is reported, because the
budget is kept per tenant and not per runner. Do not add up responses across instance_id
values: each one is the same tenant figure.
What is measured. Compute Units are model time: 1 CU is one second of holding a shared model
slot. They are recorded per call against the purchaser’s billing account, not the tenant, and
billed with the subscription (see Plans and billing). A
tenant-scoped answer can’t say whose usage it is on a shared instance, so this service reports
no CU figure. Data units (RAM) and cost are not metered either. All three are sent as 0 with an
explanation in unmeasured_reason. Show that explanation instead of the numbers, and never
display a 0 as 0 CU, $0.00 or 0 GB.
GetResourceUsage
rpc GetResourceUsage(GetResourceUsageRequest) returns (GetResourceUsageResponse);- Kind: Unary.
- Auth: Bearer session.
- Errors: None beyond authentication.
Request: GetResourceUsageRequest
| Field | Type | Description |
|---|---|---|
instance_id | string | Accepted but not used for scoping. See usage_scope. |
Response: GetResourceUsageResponse
| Field | Type | Description |
|---|---|---|
compute_units | double | Not reported here. Always 0. See unmeasured_reason. |
data_units | double | Not metered. Always 0. See unmeasured_reason. |
estimated_cost | double | Not metered. Always 0. See unmeasured_reason. |
unmeasured_reason | string | Non-empty exactly when a numeric field above is not a real measurement. Show it in place of those numbers. |
usage_scope | string | The scope the figures describe, as <prefix>:<key>. Parse it as a prefix: tenant:<id> is the tenant’s total, and is the only form an authenticated client sees. instance:<id> and unattributed:<key> are also defined. Show the scope wherever you show the numbers. |
GetComputeBudget
rpc GetComputeBudget(GetComputeBudgetRequest) returns (ComputeBudgetResponse);- Kind: Unary.
- Auth: Bearer session.
- Errors: None beyond authentication.
Returns the tenant’s self-managed CU allotment, what has been recorded against it and what
remains. A tenant that has never set a budget reports the default of 1,000 CU. While
remaining_compute_units is 0, a fetch is refused before it runs.
This budget is a control the tenant sets. It is not the plan’s CU allowance, and the word
“dedicated” in its field names has nothing to do with the Dedicated plan. Fetches no longer add
to consumed_compute_units: the figure keeps what earlier releases recorded (a flat 25 CU per
fetch), and model time is metered per billing account instead.
Request: GetComputeBudgetRequest
| Field | Type | Description |
|---|---|---|
instance_id | string | Accepted but not used for scoping. The budget is the tenant’s. |
Response: ComputeBudgetResponse
| Field | Type | Description |
|---|---|---|
instance_id | string | The budget key actually used, which is the tenant id. |
dedicated_compute_units | double | The dedicated CU allotment. |
consumed_compute_units | double | CU recorded against the budget. Fetches no longer add to it. |
remaining_compute_units | double | dedicated - consumed, never below 0. |
SetComputeBudget
rpc SetComputeBudget(SetComputeBudgetRequest) returns (ComputeBudgetResponse);- Kind: Unary.
- Auth: Bearer session.
ROLE_READERis refused. - Errors:
PERMISSION_DENIEDfor a reader.INVALID_ARGUMENTifdedicated_compute_unitsis negative.
Sets the dedicated allotment to an absolute value, so applying the same value twice has no
further effect. With an idempotency_key, a request that repeats the key of the last applied set
is not applied again. Consumption is not changed. The response is the budget after the call.
Request: SetComputeBudgetRequest
| Field | Type | Description |
|---|---|---|
instance_id | string | Accepted but not used for scoping. The budget is the tenant’s. |
dedicated_compute_units | double | The new allotment. Must be 0 or more. |
idempotency_key | string | Optional. Resending the key of the last applied set leaves the budget unchanged. |
Response
SchedulesService
Full name semantics.v1.SchedulesService.
A schedule triggers a fetch at a fixed interval. Its title is sent as the fetch command, and it
runs on the managed runner under a short-lived service-account session. Schedules are stored
durably and fire on the control plane only.
<time> — skipped (execution disabled), with
last_run_success: false, and run_count does not increase.Frequency. frequency is free text. The server reads the interval from it, case-insensitively:
| Text contains | Interval |
|---|---|
6 hour | 6 hours |
hour | 1 hour |
dail or day | 1 day |
week | 1 week |
month | 30 days |
custom | 1 day |
| anything else, or empty | 1 hour |
The stored label is the text you sent, with its first letter capitalised and the rest lowercase.
On create, an empty frequency is labelled Daily but, per the table, fires hourly. Send an
explicit frequency.
If a run is still in progress when the schedule is next due, that interval is skipped.
Event triggers. A schedule whose trigger is event has no interval: it
runs when the connection’s data listener has seen
min_events matching events, debounce_seconds after the first of them, at most once per
cooldown_seconds, and never while its previous run is in progress. The run is a fetch with
trigger_type: TRIGGER_TYPE_EVENT and job_id event:<schedule id>:<first>-<last position>;
the schedule’s event_state records the events that fired it and the
run’s transaction id. The fetch carries those events (trigger_events, with
trigger_connection_id); the runner reads the rows they name back and the run’s analysis
reports, per rule, which of them conform or break it (last_fire_rules). Only the control
plane’s event trigger can set trigger_events: a client-set value is cleared on receipt.
Creating or resuming an event schedule turns the connection’s listener on; pausing or
deleting the last active one on that connection turns it off.
ListSchedules
rpc ListSchedules(ListSchedulesRequest) returns (ListSchedulesResponse);- Kind: Unary.
- Auth: Bearer session.
- Errors: None beyond authentication.
Returns every schedule. The first time a new instance starts, it may already hold example schedules.
Request: ListSchedulesRequest
No fields.
Response: ListSchedulesResponse
| Field | Type | Description |
|---|---|---|
schedules | repeated Schedule | All schedules. |
listeners | repeated DataListenerMetering | Every connection whose data listener is on, with the state the runner last reported and the usage metered. Listing never dials the runner. |
CreateSchedule
rpc CreateSchedule(CreateScheduleRequest) returns (Schedule);- Kind: Unary.
- Auth: Bearer session, writer, admin or service account.
- Errors:
INVALID_ARGUMENTiftitleis empty or the trigger is invalid (an unknown kind, no connection, a debounce outside 0–3600 s, a cooldown outside 60–86400 s, an operation other thanINSERT,UPDATE,DELETEorPRODUCE).NOT_FOUNDif the trigger names no connection on this instance.
Creates an active schedule whose first run is one interval from now. The id is a slug of the
title, with -2, -3 and so on added when the slug is taken.
Request: CreateScheduleRequest
| Field | Type | Description |
|---|---|---|
title | string | Required. Also the fetch command the schedule runs. |
description | string | Free-text description. |
frequency | string | Interval text. See Frequency. Ignored for an event trigger. |
trigger | ScheduleTrigger | Optional. Absent or time makes a time schedule. |
notify | ScheduleNotify | Who the runs tell, and when. Unset means the schedule tells nobody. |
first_run_unix | int64 | When the first run fires, for a time schedule. It must fall after now and within one interval of it. 0 means one interval from now. Refused on an event trigger. |
persona_id | string | The persona the brief is for. Empty means nobody in particular. |
connection_ids | repeated string | The connections the brief reads. Each must be a connection on this instance (INVALID_ARGUMENT names one that is not). Empty means every connection, at each run. |
Response
The created Schedule.
UpdateSchedule
rpc UpdateSchedule(UpdateScheduleRequest) returns (Schedule);- Kind: Unary.
- Auth: Bearer session, writer, admin or service account.
- Errors:
INVALID_ARGUMENTiftitleis empty.NOT_FOUNDif no schedule hasid.
Replaces the title and description with the values sent, so an empty description clears it. An
empty frequency keeps the current one. If the frequency changes and the schedule is active, the
next run is one new interval from now. The run history and the active flag cannot be changed
here.
Request: UpdateScheduleRequest
| Field | Type | Description |
|---|---|---|
id | string | The schedule to edit. |
title | string | Required. New title. |
description | string | New description. Replaces the old one. |
frequency | string | New interval text. Empty keeps the current frequency. |
trigger | ScheduleTrigger | Optional. Changing the trigger discards events counted under the old one. |
notify | ScheduleNotify | Replaced like the other fields. Unset means the schedule tells nobody. |
persona_id | string | Replaced. Empty means nobody in particular. |
connection_ids | repeated string | Replaced. Empty means every connection, at each run. |
Response
The updated Schedule.
SetScheduleActive
rpc SetScheduleActive(SetScheduleActiveRequest) returns (Schedule);- Kind: Unary.
- Auth: Bearer session, writer, admin or service account.
- Errors:
NOT_FOUNDif no schedule hasid.
Resuming schedules the next run one interval from now. Pausing clears the next run
(next_run_unix: 0, next_run: "Manual Resume Req.").
Request: SetScheduleActiveRequest
| Field | Type | Description |
|---|---|---|
id | string | The schedule. |
active | bool | true to resume, false to pause. |
Response
The updated Schedule.
DeleteSchedule
rpc DeleteSchedule(DeleteScheduleRequest) returns (DeleteScheduleResponse);- Kind: Unary.
- Auth: Bearer session, writer, admin or service account.
- Errors: None. An unknown id returns
success: false.
Request: DeleteScheduleRequest
| Field | Type | Description |
|---|---|---|
id | string | The schedule to delete. |
Response: DeleteScheduleResponse
| Field | Type | Description |
|---|---|---|
success | bool | true if a schedule was deleted. |
Messages
Schedule
| Field | Type | Description |
|---|---|---|
id | string | Schedule id, a slug of the title. |
title | string | Title. Also the fetch command. |
description | string | Description. |
frequency | string | Frequency label. |
next_run | string | Human-readable next-run label, for example in 6h. |
last_run_success | bool | Whether the last run succeeded. |
active | bool | Whether the schedule fires. |
interval_seconds | int64 | Interval the executor uses. |
next_run_unix | int64 | Next due time. 0 when paused. |
last_run | string | Human-readable last-run label, with — failed or — skipped (execution disabled) appended when relevant. |
run_count | int64 | Runs attempted. Skipped runs are not counted. |
trigger | ScheduleTrigger | time or event, with the event condition. |
event_state | ScheduleEventState | For an event trigger: what is pending and what fired it last. |
notify | ScheduleNotify | Who the runs tell, and when. Unset, or every channel off, means nobody is told. |
last_notify | ScheduleNotifyOutcome | What the last run’s notice did. |
persona_id | string | The persona the brief is for. Empty for nobody in particular. |
connection_ids | repeated string | The connections the brief reads. Empty means every connection the instance has when the run fires. An event brief also reads its trigger’s connection, first. |
connection_names | map<string, string> | The names of those connections when the brief was saved (id to name), so a run can name one that has since gone. |
ScheduleNotify
A brief’s “tell me” setting. The notice goes to the numbers set in Settings › Integrations › Channels, and by email from the mailbox connected there.
| Field | Type | Description |
|---|---|---|
whatsapp | bool | Send a WhatsApp message. |
call | bool | Place a call. |
email | bool | Email the notice from the instance’s own mailbox to that mailbox’s address. |
condition | string | When to tell: always (the default), decisions (the run drafted at least one Twins decision), approval (at least one decision needs a person’s approval), or at_stake (a decision states at least min_at_stake dollars at stake; a decision stating none never counts). |
min_at_stake | double | The threshold for at_stake. |
ScheduleNotifyOutcome
What the last run flagged and what its notice did.
| Field | Type | Description |
|---|---|---|
transaction_id | string | The run. |
status | string | waiting (the run has not finished), sent, partly_sent, not_needed (the condition did not hold) or not_sent. |
detail | string | Why, in words. |
at_unix | int64 | When. |
measured | bool | false means the run’s decisions could not be read. The counts below are then 0 and mean “not measured”, never “none”. |
decisions | int32 | Pending Twins decisions the run drafted. |
needs_approval | int32 | Of those, how many need a person’s approval. |
at_stake_stated | bool | false means no decision stated an amount at stake. |
max_at_stake | double | The largest amount at stake a decision stated. |
channels | repeated ScheduleNotifyChannel | One entry per channel: channel (whatsapp, call or email), sent (the carrier or mail provider accepted it; not proof of delivery) and detail. |
ScheduleTrigger
| Field | Type | Description |
|---|---|---|
kind | string | time (the default) or event. |
connection_id | string | Event: the connection whose data listener feeds the schedule. |
min_events | int64 | Event: matching events needed for a run. Default 1. |
debounce_seconds | int64 | Event: wait this long after the first pending event. 0–3600. |
cooldown_seconds | int64 | Event: at least this long between two runs. 60–86400, default 600. |
match_source | string | Event: only tables or topics starting with this, case-insensitive. Empty counts every source. |
match_op | string | Event: INSERT, UPDATE, DELETE or PRODUCE. Empty counts every operation. |
ScheduleEventState
| Field | Type | Description |
|---|---|---|
pending_events | int64 | Matching events waiting for a run. |
first_pending_unix | int64 | When the first of them arrived. |
last_fired_unix | int64 | When the schedule last fired. 0 if never. |
last_fire_events | int64 | How many events fired it. |
last_fire_sample | repeated DataEvent | The events that fired it, at most 25 (the first and the newest), oldest first. |
last_fire_transaction_id | string | The run’s analysis transaction id. |
last_fire_outcome | string | running, ran, skipped: … or failed: …; once the analysis has finished, ran; analysed: … or ran; analysis produced nothing: …. |
last_fire_rules | repeated EventRuleResult | The rule results the run’s analysis attributed to the triggering rows. Empty until it finishes. |
last_fire_rows | repeated TriggerRowRef | The rows the runner read back for the run. |
last_fire_job_id | string | The run’s job_id. |
EventRuleResult
One rule result attributed to the rows that fired a run. Only keys that were triggering rows are kept; a rule that cites none is not listed.
| Field | Type | Description |
|---|---|---|
rule_id | string | The rule’s id, as on the Why page. |
name | string | The rule’s name. |
category | string | For example Finance. |
status | string | Aligned, Drift, Shadow or Missing. |
severity | string | The rule’s severity. |
logic_plain_english | string | What the rule says. |
evidence_keys | repeated string | Keys of the triggering rows the result is about. |
TriggerRowRef
| Field | Type | Description |
|---|---|---|
table | string | schema.table. |
key_column | string | The business-key column. |
key | string | The key. |
found | bool | false: no row has that key any more (deleted, or pruned since). |
DataEvent
One change a data listener saw: its coordinates, never its values.
| Field | Type | Description |
|---|---|---|
index | int64 | The listener’s own count of this event since it started on the runner. |
position | string | A ledger sequence number, or topic:partition:offset. |
source | string | Table or topic. |
op | string | INSERT, UPDATE, DELETE, or PRODUCE for Kafka. |
key | string | The row’s business key, or the record’s key. |
key_column | string | The column key is a value of. Empty for a Kafka record. |
at_unix_ms | int64 | When the change happened, by the source’s clock. |
bytes | int64 | Bytes read for this event. |
DataListenerMetering
| Field | Type | Description |
|---|---|---|
connection_id, connection_name | string | The connection. |
status | DataListenerStatus | The runner’s last report: state (starting, listening, degraded, not_listening, disabled), reason, mechanism, last_event_unix_ms, position. |
events_metered, bytes_metered, listening_seconds_metered | int64 | Cumulative across runner restarts. Events and seconds are recorded in the usage ledger as listener_events and listener_seconds. |
billed_to | string | The purchaser account the usage is recorded against, or platform. |
polled_unix | int64 | When the runner last reported. |
metering_note | string | Why the usage is not attributed to a purchaser, when it is not. |