What uses a credit
One run of one workflow uses exactly one credit, whatever the workflow asks for and however many of its steps ran. A verification that walked twelve steps and one that walked three cost the same. The credit is used when the verification ends, not when you create it:
One run uses one credit for one ending, never two. A record that completed and then expires when its
retention window closes used one credit in total; a record marked
failed or gated that later
expires used none.
A reset is a run of its own
Resetting a verification runs the subject through again, so the run it opens uses a credit of its own when that run ends.credits_consumed on the record counts every run of it, not the record:
2. One still open reads 0.
Resetting a verification that never ended adds nothing to credits_consumed: the run you cleared was
never charged for, and the one you opened is charged when it ends. Nobody having paid for that run is
exactly what makes it draw on the workflow’s reset allowance instead. See
When the resets run out.
Reading where a workflow stands
GET /workflows and GET /workflows/{workflow_key} both report credits, runs and resets:
The three figures that take credits away account for the whole of the difference, so
granted less
consumed, expired and revoked is always remaining. Reading a workflow never uses a credit, so
poll it as often as you find useful.
Credits are granted on a term
Every credit is granted on a term. Each time a workflow is topped up, the credits come with anon
date of their own: the last day they can be spent on. They are good for all of that day, and once it has passed whatever was still standing
on that term is gone. expired rises by that much and remaining falls by the same, on that date.
What a term forfeits is what it was holding on the day it passed. Runs you make afterwards come out of
the credits that are still live, never out of the ones that expired, so what a term took is settled on
its last day and does not change afterwards.
Spending draws on the term that comes up soonest, so credits are used in the order they would otherwise
be lost. Topping up never moves the date on the credits you already had: a top-up bought today carries
its own term and leaves every earlier one exactly where it was.
expiring is what to read. The workflow above holds 288 credits, but they are not one pool with one
date on it: 88 of them go at the end of September and the other 200 run to the end of March. A single
date could only have told you one of those, so the breakdown is what the API reports and the entries
are ordered by the one that matters first.
Credits that expire are the one thing that moves remaining with no verification behind it. Where
you find a balance lower than you expected and consumed has not moved, expired is the figure that
explains it.
Two balances and a ceiling, and what each one stops
The balance, the live ceiling and the reset allowance answer different questions. The balance caps the work that can finish; the live ceiling caps the work you can have in flight; the allowance caps the work you can have re-run without paying for it. A verification that has not ended has used no credit, so the three count different things and any of them can be the one in your way.
Credits and resets are both topped up by buying, but not by the same purchase, so read the
code on a
402 before asking us for more: credits-exhausted and resets-exhausted are different things to be
short of.
Which of them a reset is held to is decided by the record’s status. One reading open or submitted
is held to the allowance and never to the live ceiling, because it is holding its place already. One
reading completed or cancelled is held to the live ceiling and never to the allowance, because the
run it clears was charged for - and so is one reading failed, which draws nothing because we could
not carry that run through. One reading gated is held to both: it has ended, so reopening it takes a
place, and nobody paid for the run it clears. So the record’s own status tells you which limits a
reset of it could run into before you read anything else.
When the balance is gone
A workflow readsremaining as zero whether its credits were spent, expired or taken back, and in
every case refuses everything that would start a verification or move one along, as 402:
So a workflow that runs out stops moving without ever stopping being readable. Every record on it can
still be read, listed, counted and its documents downloaded, and you can still cancel or purge one.
The verifications already open on it are frozen where they stand until the workflow is topped up, and
nothing about them is lost.
402 is not transient. Retrying gets the same answer until the workflow is topped up, so treat it as
“ask for more credits” rather than as something to back off and repeat. See
Retrying safely.
Why remaining can read negative
A verification that has not ended has used nothing, so you can be committed to more runs than your
balance covers. When those runs end, each uses the credit it owes, and remaining goes below zero.
No more than runs.limit verifications can be in that position, so that is as far below zero as it
goes. A top-up settles the debt out of the credits it adds, and remaining comes back up.
credits.expiring is empty for as long as the balance is negative, a debt standing on no term and
expiring on no date. It fills again with the top-up that settles it.
When the live ceiling is reached
runs.limit is how many verifications a workflow may have open or submitted at once. Once
runs.live has reached it:
- Creating a verification is refused with
409. - Resetting one that had already ended is refused with
409. Reopening acompleted,cancelledorfailedrecord takes a place, the same as creating one. - Resetting one that is still
openorsubmittedgoes through. It is holding its place already, so reopening it takes no second one. - Everything else is untouched. Uploading, withdrawing, running the checks, handing off and reading are not held to the ceiling.
instant workflow is held to the ceiling too. Its verifications are open while their checks run
and end when the response is written, so each one holds a place for the length of its own request. In
practice that makes runs.limit the number of instant verifications you may have running at once: keep
that many calls in flight and no more, and the ceiling never comes up.
When the resets run out
Resetting a verification runs its subject through the checks again, which costs us what a run costs. Whether you have paid for that depends on the run you are clearing:
So
resets covers only the re-runs nobody has paid for. Re-verifying a subject you have already
paid for is never held back by it, however many resets have gone: reset a completed record as
often as you need, and each run is charged as a run. Neither is retrying a run we could not finish.
Resets are sold with credits, on the same terms, and read exactly as credits do. A sale carries a
number of them; they are drawn as you clear unpaid runs; and whatever is still standing on a term when
its last day passes is forfeited alongside the credits it came with. resets.expiring says what is
standing on what, soonest first.
Once resets.remaining reads zero, resetting an open or submitted verification is refused with
402 and the code resets-exhausted, whichever of the workflow’s verifications it is. They are held
by the workflow rather than by any one record, because an unpaid re-run costs us the same wherever it
falls.
Topping up is what fills this, as it is for credits, and resets can be bought on their own, so
running short of room to clear unpaid work does not mean buying runs you do not need. Ask us. What is
already drawn stays drawn: ending, cancelling, expiring or purging a verification gives nothing back,
so resets.drawn only ever rises.
Letting a verification end before you reset it is what keeps your resets intact, and that is not a
trick: the credit the ending charges is what pays for the re-run.
Each verification also reports its own resets, on its record and in the list it appears in, counting
every reset of it whether or not it drew on the allowance:
2 is on its third run.
An instant workflow never draws on this. Its verifications are answered in the request that made
them, so you ask about the subject again rather than resetting a record, and its resets stays where
it started.
Telling the 409s apart
The live ceiling answers 409, and so do several things that have nothing to do with credits. The
error’s code says which you hit. The reset allowance is not among them: it answers 402, alongside
the balance.
See Errors for the whole list of codes.
Running low
Credits, resets and the live ceiling are all set by us on your workflow, so ask us for any of them. Nothing here is self-serve, and there is no way to buy over the API.- Watch
credits.remainingon the workflows you run, and alert yourself well before it reaches zero. Reading a workflow is free, so there is no cost to checking often. - Watch the first entry in
credits.expiring, not just the total. It is the next date this workflow loses credits on and how many it loses, so it is the one that tells you when to top up. Credits expire by term, soremainingcan drop on a date rather than on a run, and topping up adds credits on a new term rather than extending the term of the ones you already hold. - Ask for more room on the live ceiling if
runs.livesits nearruns.limitin normal operation. How much work you may have in flight is agreed separately from how many runs you bought. - Watch
resets.remainingif you reset records before they end, andresets.expiringfor when they go. They are sold with credits and expire with them, so a workflow that clears unpaid runs as a matter of course needs them stocked like runs. Resetting records that have already completed or been cancelled never touches them. - Remember that
uatandproductionworkflows are different workflows, so each carries its own credits and its own ceilings. Testing againstuatnever draws down what you bought for real work. See Environments.