--- title: "Credits readiness check" description: "Check the plan and the credit balance before a big import or a competitor research run, and tell the user if the work can start now." url: "/docs/agents/workflows/credits-readiness-check" --- This page is an agent-readable workflow for Deck. Humans can follow along. Coding agents should treat the steps as the source of truth. # Credits readiness check — agent workflow * **Use it when:** the user asks "do we have enough credits to import 2,000 tickets?", "can I start competitor research now?" or "why do my uploads wait for credits?" * **Outcome:** the user gets one verdict (go, wait or ask an admin) with Deck's balance, the warning level and the items that wait for credits, and one next step. * **Needs:** Deck MCP. Any role with MCP access can read credits. Only organization admins add credits or turn on overage, in Settings → Billing. ## 1. Probe Deck MCP Call `get_user_context`. This must be a real tool call. * 401 Unauthorized: tell the user to connect Deck MCP in this client (Settings → Connections). Stop. * No Deck tools: fetch and follow [https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md](https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md). Stop this workflow until the tools work. * More than one Deck organization: call `select_organization`, ask which one to check, and pass its `org_id` on every later call. ## 2. Ask what the work is Ask the user what they plan to run: a CSV upload, interviews, a support ticket backfill, or competitor research. Ask for the size, for example the number of rows, files or competitors. ## 3. Read the balance Make these calls in parallel: * `explore_workspace` with `view: "credits"`. Read: * `plan.billing_tier`. * `credits.credits_remaining`, `credits.total_credits` and `credits.period_end`. * `credits.core_credits_remaining`: what imports and other background work can still use when overage is off. Deck keeps the rest for activation work. * `credits.overage_enabled`, `credits.is_blocked` and `credits.is_core_processing_blocked`. * `warning_level`: `ok`, `low`, `critical`, `items_waiting` or `exhausted`. * `blocked_items.total` and `blocked_items.by_type`. * `billing_url`, which only admins get. * `list_sources` with `statuses: ["CREDIT_BLOCKED"]`: the sources that already wait for credits. * `list_sources` with import\_source set to `CSV`: uploads with the status `CREDIT_BLOCKED`. When `credits` is null, Deck found no active credit allocation. Tell the user and stop. ## 4. Get Deck's cost figure Use only a figure that Deck gives: * Competitor research: call `explore_competitors` with `view: "settings"`. Read `credit_ceiling.credits` (the most credits one run can use), `free_window`, `plan.free_report_used`, `research_running` and `max_competitors`. * Survey CSV upload: the upload wizard shows a credit counter before the user submits. Structured answers use 0 credits. Ask the user to read the counter. * Other CSV types, interviews and tickets: Deck gives no estimate before processing, because the cost depends on the amount of text. Suggest a test batch of 20-50 items. Then call `explore_workspace` with `view: "credits"` again and give the user both balances. ## 5. Decide | Deck says | Verdict | Next step | | ---------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------- | | `warning_level` is `ok` or `low`, and Deck's cost figure is lower than `core_credits_remaining` | Go | Start the work | | `overage_enabled` is true | Go | The work can use overage credits. Overage costs money. Tell the user before they start. | | Deck's cost figure for an upload is higher than `core_credits_remaining`, and overage is off | Partly | Deck processes the rows it can now and keeps the rest as waiting for credits | | Deck's cost figure for research is higher than `core_credits_remaining`, and overage is off | Wait | Research can return `CREDIT_LIMIT_EXCEEDED`. An admin adds credits first. | | `is_blocked` or `is_core_processing_blocked` is true, or `warning_level` is `exhausted` or `items_waiting` | Wait | An admin adds credits or turns on overage. Or wait until `period_end`. | | `research_running` is true | Wait | `start_competitor_research` and `add_competitor` return `CONFLICT` until the run ends | | `plan.free_report_used` is true | Upgrade | The Free plan report is used. An admin upgrades the plan. | | `free_window` says research is free | Go | Research is free until that date. Check-ins still use credits. | When there is no Deck cost figure, give the balance and the test batch advice. Do not give a verdict for the full batch. ## 6. Report Give the verdict first. Then give Deck's numbers from steps 3 and 4 and the next step. * The user is an admin: add `billing_url`. You can also call `get_platform_links` with `resources: [{ resource_type: "settings", page: "billing" }]`. That link is marked `admin_only`. * The user is a member: write one short request that the user can send to an organization admin. See [Billing & Credits](/docs/org-settings/billing) and [Competitors settings](/docs/org-settings/competitors). ## Rules * This workflow only reads. Do not start research, uploads or imports here. After a go, the user picks the next workflow. * Quote Deck's numbers. Do not compute your own. Do not estimate the cost of a full batch from a test batch. * Never ask for card details, invoices or payment data. No MCP tool returns them. * Never ask for a `dk_` API key. * Only organization admins change Billing settings. ## Done when * The user has one verdict, Deck's balance and warning level, and one next step. * Each number in the report comes from a tool result in this session, or from the upload wizard as the user read it. --- [View full sitemap](/docs/sitemap)