Skip to content

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

ServiceRPCKindPurpose
MeteringServiceGetResourceUsageUnaryWhat is and is not measured for the caller’s tenant
MeteringServiceGetComputeBudgetUnaryRead the self-managed CU budget
MeteringServiceSetComputeBudgetUnarySet the self-managed CU budget to an absolute value
SchedulesServiceListSchedulesUnaryList schedules
SchedulesServiceCreateScheduleUnaryCreate an active schedule
SchedulesServiceUpdateScheduleUnaryReplace a schedule’s title, description and frequency
SchedulesServiceSetScheduleActiveUnaryPause or resume a schedule
SchedulesServiceDeleteScheduleUnaryDelete 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

FieldTypeDescription
instance_idstringAccepted but not used for scoping. See usage_scope.

Response: GetResourceUsageResponse

FieldTypeDescription
compute_unitsdoubleNot reported here. Always 0. See unmeasured_reason.
data_unitsdoubleNot metered. Always 0. See unmeasured_reason.
estimated_costdoubleNot metered. Always 0. See unmeasured_reason.
unmeasured_reasonstringNon-empty exactly when a numeric field above is not a real measurement. Show it in place of those numbers.
usage_scopestringThe 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

FieldTypeDescription
instance_idstringAccepted but not used for scoping. The budget is the tenant’s.

Response: ComputeBudgetResponse

FieldTypeDescription
instance_idstringThe budget key actually used, which is the tenant id.
dedicated_compute_unitsdoubleThe dedicated CU allotment.
consumed_compute_unitsdoubleCU recorded against the budget. Fetches no longer add to it.
remaining_compute_unitsdoublededicated - consumed, never below 0.

SetComputeBudget

rpc SetComputeBudget(SetComputeBudgetRequest) returns (ComputeBudgetResponse);
  • Kind: Unary.
  • Auth: Bearer session. ROLE_READER is refused.
  • Errors: PERMISSION_DENIED for a reader. INVALID_ARGUMENT if dedicated_compute_units is 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

FieldTypeDescription
instance_idstringAccepted but not used for scoping. The budget is the tenant’s.
dedicated_compute_unitsdoubleThe new allotment. Must be 0 or more.
idempotency_keystringOptional. Resending the key of the last applied set leaves the budget unchanged.

Response

ComputeBudgetResponse.

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.

Firing a schedule runs a real fetch only when the operator has enabled scheduled execution on the deployment. Otherwise each due run is recorded as <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 containsInterval
6 hour6 hours
hour1 hour
dail or day1 day
week1 week
month30 days
custom1 day
anything else, or empty1 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

FieldTypeDescription
schedulesrepeated ScheduleAll schedules.
listenersrepeated DataListenerMeteringEvery 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_ARGUMENT if title is 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 than INSERT, UPDATE, DELETE or PRODUCE). NOT_FOUND if 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

FieldTypeDescription
titlestringRequired. Also the fetch command the schedule runs.
descriptionstringFree-text description.
frequencystringInterval text. See Frequency. Ignored for an event trigger.
triggerScheduleTriggerOptional. Absent or time makes a time schedule.
notifyScheduleNotifyWho the runs tell, and when. Unset means the schedule tells nobody.
first_run_unixint64When 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_idstringThe persona the brief is for. Empty means nobody in particular.
connection_idsrepeated stringThe 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_ARGUMENT if title is empty. NOT_FOUND if no schedule has id.

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

FieldTypeDescription
idstringThe schedule to edit.
titlestringRequired. New title.
descriptionstringNew description. Replaces the old one.
frequencystringNew interval text. Empty keeps the current frequency.
triggerScheduleTriggerOptional. Changing the trigger discards events counted under the old one.
notifyScheduleNotifyReplaced like the other fields. Unset means the schedule tells nobody.
persona_idstringReplaced. Empty means nobody in particular.
connection_idsrepeated stringReplaced. 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_FOUND if no schedule has id.

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

FieldTypeDescription
idstringThe schedule.
activebooltrue 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

FieldTypeDescription
idstringThe schedule to delete.

Response: DeleteScheduleResponse

FieldTypeDescription
successbooltrue if a schedule was deleted.

Messages

Schedule

FieldTypeDescription
idstringSchedule id, a slug of the title.
titlestringTitle. Also the fetch command.
descriptionstringDescription.
frequencystringFrequency label.
next_runstringHuman-readable next-run label, for example in 6h.
last_run_successboolWhether the last run succeeded.
activeboolWhether the schedule fires.
interval_secondsint64Interval the executor uses.
next_run_unixint64Next due time. 0 when paused.
last_runstringHuman-readable last-run label, with — failed or — skipped (execution disabled) appended when relevant.
run_countint64Runs attempted. Skipped runs are not counted.
triggerScheduleTriggertime or event, with the event condition.
event_stateScheduleEventStateFor an event trigger: what is pending and what fired it last.
notifyScheduleNotifyWho the runs tell, and when. Unset, or every channel off, means nobody is told.
last_notifyScheduleNotifyOutcomeWhat the last run’s notice did.
persona_idstringThe persona the brief is for. Empty for nobody in particular.
connection_idsrepeated stringThe 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_namesmap<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.

FieldTypeDescription
whatsappboolSend a WhatsApp message.
callboolPlace a call.
emailboolEmail the notice from the instance’s own mailbox to that mailbox’s address.
conditionstringWhen 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_stakedoubleThe threshold for at_stake.

ScheduleNotifyOutcome

What the last run flagged and what its notice did.

FieldTypeDescription
transaction_idstringThe run.
statusstringwaiting (the run has not finished), sent, partly_sent, not_needed (the condition did not hold) or not_sent.
detailstringWhy, in words.
at_unixint64When.
measuredboolfalse means the run’s decisions could not be read. The counts below are then 0 and mean “not measured”, never “none”.
decisionsint32Pending Twins decisions the run drafted.
needs_approvalint32Of those, how many need a person’s approval.
at_stake_statedboolfalse means no decision stated an amount at stake.
max_at_stakedoubleThe largest amount at stake a decision stated.
channelsrepeated ScheduleNotifyChannelOne entry per channel: channel (whatsapp, call or email), sent (the carrier or mail provider accepted it; not proof of delivery) and detail.

ScheduleTrigger

FieldTypeDescription
kindstringtime (the default) or event.
connection_idstringEvent: the connection whose data listener feeds the schedule.
min_eventsint64Event: matching events needed for a run. Default 1.
debounce_secondsint64Event: wait this long after the first pending event. 0–3600.
cooldown_secondsint64Event: at least this long between two runs. 60–86400, default 600.
match_sourcestringEvent: only tables or topics starting with this, case-insensitive. Empty counts every source.
match_opstringEvent: INSERT, UPDATE, DELETE or PRODUCE. Empty counts every operation.

ScheduleEventState

FieldTypeDescription
pending_eventsint64Matching events waiting for a run.
first_pending_unixint64When the first of them arrived.
last_fired_unixint64When the schedule last fired. 0 if never.
last_fire_eventsint64How many events fired it.
last_fire_samplerepeated DataEventThe events that fired it, at most 25 (the first and the newest), oldest first.
last_fire_transaction_idstringThe run’s analysis transaction id.
last_fire_outcomestringrunning, ran, skipped: … or failed: …; once the analysis has finished, ran; analysed: … or ran; analysis produced nothing: ….
last_fire_rulesrepeated EventRuleResultThe rule results the run’s analysis attributed to the triggering rows. Empty until it finishes.
last_fire_rowsrepeated TriggerRowRefThe rows the runner read back for the run.
last_fire_job_idstringThe 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.

FieldTypeDescription
rule_idstringThe rule’s id, as on the Why page.
namestringThe rule’s name.
categorystringFor example Finance.
statusstringAligned, Drift, Shadow or Missing.
severitystringThe rule’s severity.
logic_plain_englishstringWhat the rule says.
evidence_keysrepeated stringKeys of the triggering rows the result is about.

TriggerRowRef

FieldTypeDescription
tablestringschema.table.
key_columnstringThe business-key column.
keystringThe key.
foundboolfalse: no row has that key any more (deleted, or pruned since).

DataEvent

One change a data listener saw: its coordinates, never its values.

FieldTypeDescription
indexint64The listener’s own count of this event since it started on the runner.
positionstringA ledger sequence number, or topic:partition:offset.
sourcestringTable or topic.
opstringINSERT, UPDATE, DELETE, or PRODUCE for Kafka.
keystringThe row’s business key, or the record’s key.
key_columnstringThe column key is a value of. Empty for a Kafka record.
at_unix_msint64When the change happened, by the source’s clock.
bytesint64Bytes read for this event.

DataListenerMetering

FieldTypeDescription
connection_id, connection_namestringThe connection.
statusDataListenerStatusThe runner’s last report: state (starting, listening, degraded, not_listening, disabled), reason, mechanism, last_event_unix_ms, position.
events_metered, bytes_metered, listening_seconds_meteredint64Cumulative across runner restarts. Events and seconds are recorded in the usage ledger as listener_events and listener_seconds.
billed_tostringThe purchaser account the usage is recorded against, or platform.
polled_unixint64When the runner last reported.
metering_notestringWhy the usage is not attributed to a purchaser, when it is not.