> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/ai/agent-limit.md).

# Agent limit

How the AI Agent limit is calculated, what uses it up, and how to get the most out of it.

This article explains how the Coupler.io AI Agent limit is calculated, what uses it up, and how to get the most out of it.

## Quick rules

1. **Stay in the same thread while you work on one question.** Follow-up messages sent within 5 minutes of the agent's last reply cost much less.
2. **Start a new thread for a new topic, or after a break.** Before you step away from a long thread, ask the agent to summarize where you got to. When you come back, start a new thread with that summary instead of reopening the old one.
3. **Be specific up front.** Name the data set, the metric, and the date range in your first message.
4. **Ask for summaries, not raw data.** "Revenue by month for 2026" costs much less than "show me all orders".
5. **Don't worry about the length of the answers.** Short replies save surprisingly little (see below).

The rest of this article explains why these rules work.

## A few terms

* **Thread**: one conversation with the agent. Every message in a thread builds on the ones before it.
* **Token**: a piece of a word, which is how AI models read and write text.
* **Input tokens**: everything the model reads, which is more than your message (see below).
* **Output tokens**: everything the model writes.
* **Cache**: short-term memory on the model provider's side. Re-reading something from the cache costs much less than reading it fresh.

## How AI usage is priced

AI models are priced by the number of tokens they read and write. The Coupler.io AI Agent runs on Anthropic's Claude models through the API (currently Claude Sonnet; we upgrade as new models come out). You can see the current prices on [Anthropic's pricing page](https://platform.claude.com/docs/en/about-claude/pricing).

**AI Agent credits roughly correspond to the API cost of your conversations.** You can find the current AI Agent limit for each plan on the [Coupler.io pricing page](https://www.coupler.io/pricing).

On the pricing page, output tokens cost 5 times as much as input tokens. That makes it tempting to ask the agent for shorter answers. In practice, our analysis of the last 30 days of usage shows that **about 95% of the cost comes from input tokens**. For most users, the length of the answers is not what uses up the limit. The exception is when you have the agent write long reports, where output takes a bigger share.

## Why most of the cost is input

When you send a message, the agent doesn't answer in one step. It works through your question: it finds the right data set, reads its schema, runs a query, looks at the result, and sometimes runs another query before it answers. Each of these steps is a separate call to the model, and **each call re-reads the whole conversation so far**. That includes:

* the agent's instructions and the descriptions of its tools, which are sent on every call,
* every message in the thread,
* every schema and query result the agent has already seen.

So a single question can mean a dozen calls, each reading thousands of tokens, followed by a short answer. The longer the thread and the bigger the query results, the more each step costs.

## How caching helps, and when it doesn't

To keep input costs down, the agent uses **prompt caching**. The conversation is stored in a short-term cache, and re-reading it from the cache costs only a fraction of the normal price. Writing to the cache costs a bit more than a normal read. At the time of writing, Anthropic charges 1.25× the normal input price to write to the cache and 0.1× to read from it. These numbers may change, both on Anthropic's side and on ours.

**The cache expires after 5 minutes without activity.** The timer restarts every time the agent uses the cache, so it effectively runs from **when the agent finishes its last reply**, not from when the thread started.

An example:

* **10:00** You ask a question. The conversation is written to the cache.
* **10:01** The agent replies.
* **10:04** You ask a follow-up, 3 minutes after the reply. The cache is still warm, so the history is read cheaply.
* **10:06** The agent replies, and the 5-minute timer starts again.
* **10:10** You ask another follow-up, 4 minutes after the last reply. The thread started 10 minutes ago, but the cache is still warm, because only the time since the last reply counts.
* **10:12** The agent replies.
* **10:40** You come back with another question, 28 minutes after the last reply. The cache has expired, so the **whole thread is written to the cache again** at the higher price.

For a short thread, that last step doesn't matter much. For a long thread with many query results, it can use up a noticeable part of your limit in a single message. So before you take a break, ask the agent to summarize what you've found so far while the cache is still warm. When you come back, paste the summary into a new thread. If you've already left, start a new thread and restate the key points yourself rather than asking the old thread for a summary.

## Do's and don'ts

**Do:**

* Keep going in the same thread while you're actively working on one question.
* Start a new thread for each new topic. Before you leave a long thread, ask the agent for a short summary and use it to start the next one.
* Name the data set, metric, and date range in your first message. Every exploration step the agent can skip saves a full re-read of the thread.
* Ask for totals and breakdowns ("sessions by channel, last 90 days") rather than raw rows. Small results stay cheap on every later step.
* Fill in the [business context](/ai/context/business-context.md) for your data sets. The agent then finds what it needs faster and asks fewer clarifying questions.

**Don't:**

* Come back to a long thread after a break, like after lunch or the next day. Start a new one with a summary.
* Ask an old thread for a summary after a break. That rewrites the whole conversation to the cache. Get the summary before you leave.
* Ask the agent to "show all rows" or dump a whole data set.
* Use one thread for everything all day. Every message gets more expensive as the thread grows.
* Rely on "keep your answers short" to save credits. Output is only a small part of the cost.

## What we're doing on our side

The Coupler.io team keeps working to make the agent cheaper to run: shorter answers, a smaller set of instructions, and newer models that use fewer tokens.

## If you reach your limit

Contact our support team and we can give you a one-time limit increase.

We're also considering usage-based pricing for the AI Agent, so you'd never run out of credits. [Sign up](https://railsware2.typeform.com/to/KYGla3RV#email=xxxxx\&country=xxxxx\&environment=xxxxx\&user_id=xxxxx\&account_id=xxxxx\&dashboard=xxxxx) to be notified when it's available.

## Use Coupler.io in your own AI tool

Everything the agent can do is also available in your own AI tool, such as Claude or ChatGPT, through the Coupler.io [MCP](/ai/mcp.md) server. That usage runs on your AI tool's plan and **doesn't use your Coupler.io AI Agent credits**. For setup instructions, see your tool's page under [Destinations → AI integrations](https://docs.coupler.io/destinations/categories/ai).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/ai/agent-limit.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.