# Credits

Credits pay for posting to X and the X reads Flaghand makes for you. Your plan includes credits every month.
Approval shows and sets aside the most a post can spend; Automations lets you and your agent control the reads it runs.
`getCredits.spends` lists what spends credits now, and `prices` gives each action's rate.

## What spends credits

Each of these is an automation with its own settings:

- **Watching an X account or a topic.** Each watched account and each topic is its own automation.
- **Replies to your posts.** Reading the replies your posts get.
- **Reading the posts you reply to.** The post a suggested reply answers: read when the draft is checked, and read
  again when a draft, suggestion or approval shows it after its copy has gone stale.
- **Voice learning.** Reading your recent X posts to start your voice profile, only when you start or confirm it.
- **Media from your X posts.** Reading one of your posts when you or your agent import its photos, videos or GIFs.
- **Reply suggestions.** Three replies Claude writes for a comment on your YouTube videos, when you or your agent ask
  for them: usually 1 to 3 credits a time, for what the model used.

Drafting, scheduling, approving and importing your X archive don't spend credits; checking a draft spends only on
the post it replies to. Posting what you approve, reading it back once it's live, delayed reposts, a plug's checks,
take-downs and best times spend only while their feature is listed in `getCredits.spends`, as
[Posting on credits](https://app.flaghand.com/docs/credits#posting-on-credits) explains. Posting to LinkedIn and TikTok doesn't spend credits.
Posting to Bluesky doesn't spend credits either.

## What a read costs

| Reading | Credits |
| --- | --- |
| A post | 1 |
| An X account's profile, or a post's author | 2 |

A post that you, or anyone else using Flaghand, already read today costs nothing again until midnight UTC.
`getCredits` lists the cost of each kind of read in `prices`.

## Before and after it runs

Before anything that spends credits, you see the most it can spend: **Up to {n} credits**. It never spends more. Most
runs spend far less, because a watch reads only what's new and repeats are free. Afterwards you see **Spent {n}
credits**. Agents get the same numbers: `estimateAutomation` before, and `credits: { spent, balance }` in the answer of
every call that can spend them: the automation runs, watch and reply reads, voice learning, and the draft,
suggestion and approval calls that check or show the post a reply answers.

## Running out

When there aren't enough credits for the next read, nothing is read and nothing is charged. The automation pauses with
one line, for example:

> Watching @example paused: out of credits. Add credits, or it resumes on Nov 14 when your plan's credits arrive.

> Replies to your posts paused: it reached its 500-credit budget for November. Raise it in Automations, or it resumes on Dec 1.

It resumes by itself when credits arrive, and a watch then reads only within its lookback, not everything it missed.
Suggested replies show the post they answer as a link until then. Flaghand never charges you or buys credits on its
own.

## Your settings

For each automation, in Automations or through the API:

- **On or off.**
- **A monthly budget**: the most it may spend in a plan month. There's no budget unless you set one.

Your agent sets the rest through the API:

- **Lookback** (watches): how far back a watch reads when it starts or resumes. 7 days unless you change it. A topic
  can look back at most 7 days (X's search); an account as far as X allows (its latest 3,200 posts).
- **Posts to learn from** (voice learning): how many of your recent posts it reads. 200 unless you change it; up to 3,200.

Voice learning is refused before it starts if its whole ceiling doesn't fit your credits or its budget; the message
says how many posts would fit. If it runs out partway, it pauses and carries on from where it stopped once credits
arrive.

## Posting on credits

While its feature is listed in `getCredits.spends`, each X action has the following rate. `x_posting` covers posts,
alt text and posting checks; `x_readback` covers read-back and checking again; `x_reposts` covers delayed reposts;
`x_plug_checks` covers a plug's checks; `x_post_deletes` covers take-downs; `x_best_times` covers best times' reads.
These features can spend independently. Read `prices` for current rates:

| Action | Credits |
| --- | --- |
| An X post | 3 |
| An X post with a link | 40 |
| A repost | 3 |
| Taking a post down | 1 |
| Alt text on a photo or video | 1 |
| Reading a post back, or the post a reply goes under | 1 |
| Checking the account can post long posts | 2 |

A link is anything X turns into a link, with or without `https://`: `myshop.store/fall` is a link post.

**An X post: up to 4 credits**, the post and one read to check it's live. A thread adds each part, a read of
the part above each reply, and each part's check. A delayed repost adds 3 for the repost and a read of the post before
reposting it and one to find its live time. A plug adds its own post and its checks of post 1, hourly for 8 days.

- **Approving sets it aside.** The approval sheet shows the most the post can spend, **Up to {n} credits · you have
  {m}**, and approving sets that much aside for it. If you don't have that many, nothing is approved and the sheet
  says so; add credits and approve again. If the post would need more than the sheet showed by the time
  you approve (a price went up), nothing is approved and the sheet opens again with the new number.
- **It goes out as approved.** A post you approved never waits for credits, even if your balance reaches zero before
  it posts, and its plug checks post 1 for the full 8 days while your plan is active. It never spends more than it set
  aside, even if a price goes up after you approved it.
- **What it doesn't spend comes back** when its job ends: after it's posted and checked, after its repost or plug, or
  when you cancel it or it fails. Most posts spend less than their **Up to**, because a post already read today costs
  nothing again. Each job shows **Up to {n} credits · spent {m}** while it holds them.
- **It comes out of the month you approved it in.** If a post is cancelled or fails after that plan month ended,
  included credits it held end with their month; bought credits go back to your balance.
- **A take-down never waits for credits.** It spends 1 credit if you have one, and is free if you don't.
- **Checking a post again** on request spends from your balance, and is refused with nothing read at zero.
- **A read-only API token never spends credits.** Checking a post again needs the `drafts` scope while it spends, and
  best times answers a read-only token from what it last read. Reading a draft, an approval request, a suggestion, an X
  reply or a watched post with it reads nothing from X, so anything past its window comes back unavailable, and Check
  says it needs the `drafts` scope. A token that can act, such as one asking for approval, pays for what that act needs.
- **Best times** spends as it reads your posts and pauses at zero with one line, keeping the best times it already
  has and where it stopped. Once credits arrive, or its budget's next month starts, it reads on from there, so no post
  is skipped or paid for twice. `estimateAutomation` for `x_best_times` shows its **Up to** before it runs.

Posts approved before posting spent credits go out free. Once `spends` lists `x_posting`, the
[300-post / 30-link allowance](https://app.flaghand.com/docs/billing.md#monthly-x-allowance) ends; it does not run alongside posting credits.

## Included and bought credits

Included credits arrive at the start of each plan month; a yearly plan gets them every month too. Included credits are
spent before bought ones, and among them the ones that end soonest go first. `getCredits` shows each batch with what's
left and when it ends, the next included credits and their date, and `rollover`: whether a month's unused included
credits carry over. Bought credits never expire. Deleting your account deletes your credits with it. Billing shows
your balance and every credit added or spent.

## Buying credits

Only you buy credits, and only when you choose to: Flaghand never buys them for you, never charges a card later on
its own, and never reloads automatically. Buying needs an active plan; a free start adds a card first.

- **In Billing.** Tap **Add credits** on your balance (in Billing or Automations, or on an automation paused for credits).
  Pick a pack and how many, see the credits and the price, then continue to Stripe Checkout: one payment for the packs.
  Includes VAT/GST outside the US and Canada; US and Canadian tax is added at checkout where it applies.
  Back in Billing, your new balance shows once the payment goes through.
- **When your agent asks.** It sends you a link with its note. The page shows the credits, the price and the note in
  its own words. Pick how many packs, tap **Continue to payment**, confirm with your passkey, then pay in Checkout.
  Your agent never gets the Checkout link and can't pay for you; decline, and nothing happens.

The credits arrive once Stripe says the payment went through, exactly once, and automations paused for credits resume.
Bought credits never expire and work while your plan is active. A refund takes back the refunded share of that
purchase's credits, from what's still unspent, and gives them back if the refund fails or is canceled; while a payment
is disputed its unspent credits are held, and they come back if the dispute is decided for you. One Checkout takes at
most Stripe's maximum for a single payment; past it, the error says how many packs fit.

## For agents

Paths are relative to `https://app.flaghand.com/api/v1/workspaces/{workspace}`.

| Operation | Method and path | Permission | CLI |
| --- | --- | --- | --- |
| `getCredits` | `GET /credits` | read | `flaghand credits get` |
| `listCreditActivity` | `GET /credits/activity` | read | `flaghand credits list-activity` |
| `listAutomations` | `GET /automations` | read | `flaghand automations list` |
| `getAutomation` | `GET /automations/{id}` | read | `flaghand automations get` |
| `updateAutomation` | `PATCH /automations/{id}` | drafts token or owner session | `flaghand automations update` |
| `estimateAutomation` | `GET /automations/{id}/estimate` | read | `flaghand automations estimate` |
| `runAutomation` | `POST /automations/{id}/run` | drafts token or owner session | `flaghand automations run` |
| `listCreditPacks` | `GET https://app.flaghand.com/api/v1/credit-packs` | none | `flaghand credits list-packs` |
| `requestCreditPurchase` | `POST /credits/purchases` | billing token or owner session | `flaghand credits request-purchase` |
| `getCreditPurchase` | `GET /credits/purchases/{id}` | read | `flaghand credits get-purchase` |
| `listCreditPurchases` | `GET /credits/purchases` | read | `flaghand credits list-purchases` |

Automation ids are `x_replies`, `x_reply_targets`, `x_voice_bootstrap`, `x_best_times`, `x_media_import` and each watch's id (`xwa_…`). MCP: find them
with `getOperation`, read through `callReadOperation`, change and run through `callWriteOperation`.

- **Settings.** `updateAutomation` takes any of `enabled`, `budget` (credits per plan month, or `null` for none),
  `lookback_days` (watches) and `voice_posts` (voice learning). Raising or clearing a budget lifts its pause at once.
  This is by design: a token with the `drafts` scope can set, raise or clear any automation's budget and run any
  automation. It only spends credits already in the balance, never money; buying credits takes the owner's passkey.
- **Run now.** `runAutomation` refreshes one of this workspace's watches, reads new replies to its posts, refreshes
  best times, or asks to learn the owner's voice; nothing else. Pass `max_credits` to spend less than the estimate: it
  holds across every read the run makes. A token's voice learning request waits for the owner, who confirms it in
  Flaghand (`bootstrap.confirm_url`) and reads within that `max_credits`; `bootstrap.planned` shows the posts and
  credits the owner will see. `status: "partial"` means the next scheduled turn carries on from where it stopped. The
  post a draft replies to is read when the draft is checked, not run on its own.
- **Approvals.** While posting spends credits, `startApproval` answers with `set_aside` (`up_to`, `balance` and the
  sheet's line) and each item's `credits` (`credits`, `line` and `made_of`: each action, how many and its credits). Too
  few credits is the `out_of_credits` problem on that draft, before any passkey. A job's `credits` says what it set
  aside, spent and when the rest came back (`returned_at`).
- **Activity.** `listCreditActivity` lists credits added and spent, newest first; pass `automation` for one
  automation's spends and follow `next_before`.
- **Errors.** `out_of_credits` (402) and `credit_budget_reached` (409) carry the pause line in `message`; nothing was
  read. `credit_run_limit` (409): the run reached its `max_credits` or voice learning's ceiling. `automation_off` (409):
  turn it on first. Never retry these in a loop: the automation resumes by itself.

- **Before signing up.** While credits are on, `listPlans` (`GET https://app.flaghand.com/api/v1/plans`, no sign-in) gives each
  plan's `included_credits`, the free days' `free_start.credits`, and `credits`: what spends them (`spends`), the
  `prices`, `rollover` and the `packs` on sale. Flaghand's pricing page and its `llms.txt` show the same numbers.

- **Buying.** Only the owner buys. `requestCreditPurchase` takes a `pack` from `listCreditPacks`, an optional
  `quantity` (packs, default 1) and your `reason`, which the owner sees quoted as your note. It returns `approval_url`
  and `for_person`: relay that line unchanged with the link. Nothing is charged and no Checkout exists until the owner
  confirms with their passkey and pays; you never get a Checkout URL. Poll `getCreditPurchase` (`state`: `requested`,
  `open`, `paid`, `expired`, `failed` or `declined`); `credits` is what arrives once it's `paid`. Ask once: don't
  repeat a request the owner hasn't answered. Buying needs an active plan (`workspace_inactive` otherwise).