On this page
How Credits Work#
Credits are Gydr's single unit of metered usage. Every plan includes a monthly allocation, and every operation that costs real compute — answering a chat turn, embedding a knowledge base row, crawling a page — draws from it. This page is the only place in the documentation that carries costs; the rest of the reference describes behaviour, not price.
The seven metering buckets#
Chat usage is itemised across seven buckets. They appear as the credits object on every conversation response and webhook payload, and as separate tiles in Console → Usage History. All seven keys are always present; a bucket that did not apply to the turn is 0.
| Bucket | What it meters |
|---|---|
chat | The AI model that wrote the reply. |
retrieval | Searching your knowledge base for content relevant to the question. |
orchestration | The planning and quality checks that coordinate the response. |
embedding | Knowledge base indexing. Always 0 on a chat response — charged when you sync knowledge base content. |
rerank | Re-ordering retrieved results so the most relevant ones reach the model. |
plugin | External tools and integrations the agent called during the turn. |
pluginRerank | Smarter ranking of a connected store's search results (Shopify, WooCommerce) when you turn it on in the plugin's Search tab. Priced per 500 tokens scored, with a minimum of one credit per search that ranks — separate from the knowledge base rerank line. |
crawler | Website crawling. Always 0 on a chat response — charged when you run a crawl. |
API operation costs#
Every Integration API request draws credits. Cost follows the class of operation, not the resource — products, FAQs, and locations are priced identically.
| Operation | Credits | Example |
|---|---|---|
| Read | 1 | List products, get a single FAQ |
| Write | 2 | Create or update a product or FAQ |
| Delete | 1 | Delete a single record |
| Bulk create | 2 × count | 50 products = 100 credits |
| Upsert | 1 × inspected + 1 × written | 100 rows, 12 changed = 112. A failed row costs nothing; an unchanged row costs the inspected rate. |
| Reconcile | 1 per 100 scanned + 1 × deleted | Reading is priced like a list, so a dry run over 10,000 rows costs 100. |
| Bulk delete | 1 × count | 50 products = 50 credits |
| Sync | 0 to trigger | Embedding is metered per item embedded; unchanged rows are skipped. Sync status costs 1. |
| Conversation: create, end, rate, read | 1 | Create a session, end it, fetch messages |
| Conversation: send message | Token-based + 2 | The chat turn itself, plus a 2-credit API surcharge |
Every API response carries meta.creditsConsumed, so you can attribute cost per request without polling a separate endpoint. A request that fails validation is not metered. When the balance is exhausted the API returns 402 and the operation does not run.
What each feature consumes#
| Feature | Cost |
|---|---|
| Website crawler | Discovery — fetching the list of pages — is free. Credits are charged only when the crawl runs, in the saving phase. The Console shows an estimate once you have selected pages; the actual cost can land slightly either side of it. A crawl will not start if the balance is short. |
| Document upload | Metered per item embedded. Scanned PDFs and images additionally meter OCR per page. The Console estimates before you upload. |
| Visitor attachments | 2 credits per MB, rounded up to the next whole MB, minimum 1 MB per file — a 4 MB PDF costs 8. Charged when the message is sent, not when the file is uploaded. Files uploaded but never sent, rejected by content validation, or dropped by ownership checks cost nothing. |
| Data Form responses | 1 credit per response saved — per row created, never per page answered, so a long form costs the same as a short one. A form is not offered to a visitor while the balance is empty. |
| Follow-up suggestions | Off by default. When you turn it on, each answered reply in the chat widget, Messenger, Instagram and Telegram gets up to three suggested next questions (never on WhatsApp, where every message is billed), written by one extra AI call and listed as its own Follow-up suggestions line in Usage History — typically a few credits per reply. It is charged on Bring Your Own Model widgets too, because it always runs on Gydr. Suggestions are skipped, at no cost, when the balance cannot cover them, and are only shown once they are paid for. |
| Visitor memory | Off by default. When you turn it on, each eligible reply is followed by one small AI call that picks out details worth remembering for the visitor's next visit. It is charged on the Orchestration line in Usage History, separately from the reply's own credits, and on Bring Your Own Model widgets too, because it always runs on Gydr. When the balance is empty, nothing new is remembered and nothing is charged. Recalling what was already remembered costs nothing. |
| Bring Your Own Model | A chat turn that succeeds on your imported model charges zero chat credits — your provider bills you for those tokens directly. Every other bucket is unchanged: orchestration, retrieval, rerank, and plugin calls still meter as normal. If a turn falls back to a Gydr model, chat credits apply to that turn. |
Desk and CRM integrations#
Everything Gydr sends to a desk is free. Credits are drawn when a desk agent acts on a conversation, and when a lead is exported to a CRM. This applies to every desk, including Custom Desk.
| Operation | Credits | Notes |
|---|---|---|
| Desk agent reply | 1 | Per reply saved to the conversation. A reply that is rejected (too long for the visitor's channel, or no active handoff) costs nothing. |
| Desk close | 1 | When the desk closes a conversation and that ends the session. |
| Desk release | 1 | When the desk hands a conversation back to the assistant. |
| Desk takeover | 1 | When a desk agent takes over a conversation the assistant was handling. |
| Support ticket filed | 1 per ticket | When a visitor's ticket is created on the desk. The short summary drafted for the ticket form is charged separately, like any other assistant call, and only when the visitor is shown it; it is never drafted when the balance is empty. A ticket that fails, or a retry of one already filed, costs nothing. |
| CRM lead export | 1 per export, per CRM | Charged when the lead is written to the CRM. A failed export, or a retry of one already charged, costs nothing. |
| Anything Gydr sends to a desk | Free | Handoff requests, mirrored messages, session and handoff end notices, availability checks, and connection tests. |
A repeated event (the same event ID sent again), an action that changes nothing, a rate-limited call, and a request with a bad signature are never charged.
When credits run out#
With no credits left (or a payment overdue), the assistant cannot answer. A widget that has a desk connected then offers only the human path: the visitor can ask for a person, or sees the business's other contact options when no agent is available. The assistant does not run.
- Desk and CRM charges are deferred, not lost. When the balance cannot cover one, it is recorded as owed and taken from the next top-up or renewal. Conversations already in a handoff always finish, and CRM exports keep running.
- There is a limit. Once the amount owed reaches it, the widget stops offering the human path until credits are added.
- Support tickets still go through. A visitor can leave a ticket for a team that takes tickets, and a ticket started before the balance ran out is not lost. Tickets are not offered while a payment is overdue.
- Widgets without a desk connected, and API calls, behave as before: the widget shows that chat is unavailable and the API returns
402.
Allocation and top-ups#
Each plan includes a monthly credit allocation that resets on the 1st of the month. Current balance, per-bucket consumption, and the transaction history live in Console → Usage History. Additional credit packs can be purchased from the Upgrade page at any time.
Watch the balance from your own systems
Rather than polling, subscribe to webhooks and accumulate credits per turn, or read meta.creditsConsumed on each API response. Both are exact and require no extra request.