> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Limits and numbers across Hamsa Agents

> Every limit in Hamsa Agents by area: call length, concurrency, name and text lengths, knowledge base files, voices, tools, batch calls and credit expiry.

This page collects the numbers that apply across Hamsa Agents in one place, one table per area. Each row links to the page that explains the setting. Limits that depend on your plan, such as how many calls can run at once, are shown on the Plans tab of [Billing](https://docs.tryhamsa.com/overview/billing.md).

## Calls

| Limit | Value | More |
| - | - | - |
| **Max call duration** | 0.5 to 60 minutes, in steps of 0.5. Default 5 minutes. | [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md#maximum-call-length) |
| Message at the maximum call length | Optional, up to 2,000 characters | [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md#maximum-call-length) |
| **User inactivity timeout** | 5 to 60 seconds. Default 15. | [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md#when-the-caller-goes-quiet) |
| **Response delay** | 100 to 1,500 ms, in steps of 100. Default 400 ms. Values under 250 ms act as 250 ms. | [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md#turn-taking-and-interruptions) |
| **Minimum interruption duration** | 0.2 to 1.5 seconds. Default 0.5. | [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md#turn-taking-and-interruptions) |
| **VAD activation threshold** | 0.2 to 0.9. Default 0.5. | [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md#turn-taking-and-interruptions) |
| **Expressiveness** | 0 to 2, in steps of 0.1. Default 1. | [Voice, language and dialect](https://docs.tryhamsa.com/agents/settings/voice-and-language.md#voice-settings-reference) |
| **Temperature** (single prompt) | 0 to 1, in steps of 0.1. Flow agents always run at 0. | [Choose the model](https://docs.tryhamsa.com/agents/settings/model.md#temperature) |
| Reply length on Groq models | 250 tokens per reply | [Choose the model](https://docs.tryhamsa.com/agents/settings/model.md#what-the-choice-changes-on-a-call) |
| Prompt length | No maximum. The whole prompt is sent on every turn. | [Write a prompt](https://docs.tryhamsa.com/agents/build/write-a-prompt.md) |
| A "slow" reply | Over 1.5 seconds, in the Conversation log and Analytics | [Analytics](https://docs.tryhamsa.com/agents/monitor/analytics.md) |

## Calls at the same time

Your plan sets how many voice agent calls can run at once. The limit belongs to the project Owner's account: calls in all of that Owner's projects count toward it.

| Call type | When the limit is reached | More |
| - | - | - |
| Inbound phone and website calls | Refused with "Voice agent concurrency limit reached. Please wait for an active call to finish." | [Phone numbers](https://docs.tryhamsa.com/agents/connect/phone-numbers.md#how-an-inbound-call-is-answered) |
| Outbound calls from the API | Wait and try again every 30 seconds, for up to about an hour | [Outbound calls](https://docs.tryhamsa.com/agents/connect/outbound-calls.md#how-the-call-goes) |
| Batch calls | Each batch call reserves its own concurrency, from 1 up to the plan limit. The concurrency of all **Scheduled**, **In progress** and **Paused** batch calls together must fit in the limit. | [Batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md#concurrency) |
| Calls in **Pending** | Count against the limit until they start or you end them | [Conversation log](https://docs.tryhamsa.com/agents/monitor/conversation-log.md#end-calls-that-havent-started) |

## Agents and flows

| Limit | Value | More |
| - | - | - |
| Agent name | Required, up to 150 characters. Names don't have to be unique. | [Create an agent](https://docs.tryhamsa.com/agents/build/create-an-agent.md) |
| Agents per project | No limit | [Create an agent](https://docs.tryhamsa.com/agents/build/create-an-agent.md#good-to-know) |
| Greeting (single prompt) | Required, up to 191 characters | [Single prompt agents](https://docs.tryhamsa.com/agents/build/single-prompt.md#write-the-greeting) |
| Step label | Up to 100 characters | [Step types](https://docs.tryhamsa.com/agents/flow/steps/overview.md) |
| Start steps per flow | Exactly one | [Step types](https://docs.tryhamsa.com/agents/flow/steps/overview.md) |
| **DTMF input** transitions on a step with DTMF capture | At most two, `*` and `#` | [Keypad input](https://docs.tryhamsa.com/agents/flow/keypad-input.md) |
| Wait for a live variable before a reply | Up to 1.5 seconds | [Flow settings](https://docs.tryhamsa.com/agents/flow/flow-settings.md) |
| **Tool** step response | The tool's **Timeout** (1 to 60 seconds, default 5), then **On Failure** | [Tool step](https://docs.tryhamsa.com/agents/flow/steps/api-request.md#how-it-works-on-a-call) |
| **Web tool** step reply | Up to 15 seconds, then **On Failure** | [Web tool step](https://docs.tryhamsa.com/agents/flow/steps/web-tool.md#how-it-works-on-a-call) |
| Processing messages back to back | Skipped if another one ended less than 5 seconds ago | [Tool step](https://docs.tryhamsa.com/agents/flow/steps/api-request.md#how-it-works-on-a-call) |
| Warm transfer | Up to 3 attempts, 5 minutes in total, 90 seconds for each to be answered. The caller hears an update every 30 seconds. | [Transfer call step](https://docs.tryhamsa.com/agents/flow/steps/transfer-call.md#cold-or-warm) |

## Variables and Jinja

| Limit | Value | More |
| - | - | - |
| Dynamic, extracted and local variable names | Lowercase letters, numbers and underscores, starting with a letter, up to 50 characters | [Variables](https://docs.tryhamsa.com/agents/variables/overview.md) |
| **Enum values** on an extracted variable | Up to 100 characters each | [Extract values](https://docs.tryhamsa.com/agents/variables/extracted-variables.md) |
| Environment variable keys | Capital letters, numbers and underscores, starting with a letter, up to 64 characters | [Environment variables](https://docs.tryhamsa.com/agents/variables/environment-variables.md) |
| Environment variable values | Up to 4,096 characters. Every key needs a value in every environment. | [Environment variables](https://docs.tryhamsa.com/agents/variables/environment-variables.md) |
| Environments | dev, staging and prod. You can't add, rename or remove them. | [Environments and releases](https://docs.tryhamsa.com/agents/release/environments.md) |
| Test values | Up to 50 per draft. Keys up to 64 characters, values 1 to 4,000 characters. | [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md#use-test-values) |
| Jinja preview | Templates up to 100,000 characters | [Jinja syntax](https://docs.tryhamsa.com/agents/variables/jinja.md) |
| Value types | Every value reaches the call as text | [Jinja syntax](https://docs.tryhamsa.com/agents/variables/jinja.md#every-value-is-a-string) |

## Tools and secrets

| Limit | Value | More |
| - | - | - |
| **Tool name** | Up to 250 characters, unique in the project, with at least one letter | [Connect an API](https://docs.tryhamsa.com/agents/tools/api-tools.md#settings) |
| **Description** | Up to 1,000 characters | [Connect an API](https://docs.tryhamsa.com/agents/tools/api-tools.md#settings) |
| Tool and MCP server URL | Must start with `https://` | [Connect an API](https://docs.tryhamsa.com/agents/tools/api-tools.md#settings) |
| **Timeout** (single prompt agents) | 1 to 60 seconds. Default 5. | [Connect an API](https://docs.tryhamsa.com/agents/tools/api-tools.md#timeouts) |
| Error response passed to a single prompt agent | The first 400 characters | [Connect an API](https://docs.tryhamsa.com/agents/tools/api-tools.md#how-it-works-on-a-call) |
| Retries on calls | None | [Tool step](https://docs.tryhamsa.com/agents/flow/steps/api-request.md#how-it-works-on-a-call) |
| Secret names | Letters, digits, underscores and hyphens, unique in the project, case sensitive | [Secrets](https://docs.tryhamsa.com/agents/tools/secrets.md) |

## Knowledge base

| Limit | Value | More |
| - | - | - |
| Text item name | Up to 100 characters | [Add to the knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/add-items.md) |
| Text item content | 50 to 25,000 characters | [Add to the knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/add-items.md) |
| File types | PDF (.pdf), Word (.docx, .doc), plain text (.txt), Markdown (.md), web page (.html), e-book (.epub) | [Add to the knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/add-items.md#supported-files) |
| File size | Up to 21 MB per file | [Add to the knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/add-items.md#supported-files) |
| File item name | Up to 100 characters | [Add to the knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/add-items.md) |
| Number of items | No limit. Only storage counts. | [Knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/overview.md#storage) |
| Storage | Set by your plan, per project. The meter warns from 90%. | [Knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/overview.md#storage) |
| Website (URL) items | Not available | [Add to the knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/add-items.md#good-to-know) |
| A chunk | Up to 6,000 characters | [Review chunks and index](https://docs.tryhamsa.com/agents/knowledge-base/review-and-index.md) |
| Chunks per item | Up to 5,000 | [Review chunks and index](https://docs.tryhamsa.com/agents/knowledge-base/review-and-index.md) |
| Changes in one save of **Review chunks** | Up to 500 | [Review chunks and index](https://docs.tryhamsa.com/agents/knowledge-base/review-and-index.md) |
| **Chunk size** | 50 to 1,500 tokens. Default 400. | [Chunking settings](https://docs.tryhamsa.com/agents/knowledge-base/review-and-index.md) |
| **Minimum chunk size** | 0 to 500 tokens. Default 40. | [Chunking settings](https://docs.tryhamsa.com/agents/knowledge-base/review-and-index.md) |
| **Maximum chunk size** | 100 to 1,800 tokens. Default 1,800. | [Chunking settings](https://docs.tryhamsa.com/agents/knowledge-base/review-and-index.md) |
| **Overlap** | 0 to 300 tokens, and at most half the chunk size. Default 0. | [Chunking settings](https://docs.tryhamsa.com/agents/knowledge-base/review-and-index.md) |

On a call:

| Limit | Value | More |
| - | - | - |
| Passages per search | Up to 3, each shortened to about 600 characters | [How the agent searches](https://docs.tryhamsa.com/agents/knowledge-base/overview.md#how-the-agent-searches-on-a-call) |
| Wait for the search on each turn (**Agentic RAG** off) | Up to 2 seconds | [How the agent searches](https://docs.tryhamsa.com/agents/knowledge-base/overview.md#how-the-agent-searches-on-a-call) |
| Wait for each search (**Agentic RAG** on) | Up to 5 seconds | [How the agent searches](https://docs.tryhamsa.com/agents/knowledge-base/overview.md#how-the-agent-searches-on-a-call) |
| Passages kept in memory | For 3 turns after they last matched | [How the agent searches](https://docs.tryhamsa.com/agents/knowledge-base/overview.md#how-the-agent-searches-on-a-call) |
| Turns that don't start a search | Under three words, or only filler words | [How the agent searches](https://docs.tryhamsa.com/agents/knowledge-base/overview.md#how-the-agent-searches-on-a-call) |

## Voices and dictionaries

| Limit | Value | More |
| - | - | - |
| Audio formats for a new voice | MP3, WAV, WebM, OGG, AAC, M4A, FLAC | [Add a voice](https://docs.tryhamsa.com/agents/voices/add-a-voice.md#audio-limits) |
| Audio file size | Up to 35 MB | [Add a voice](https://docs.tryhamsa.com/agents/voices/add-a-voice.md#audio-limits) |
| Shortest audio | 3 seconds | [Add a voice](https://docs.tryhamsa.com/agents/voices/add-a-voice.md#audio-limits) |
| Part the voice is cloned from | 3 to 20 seconds | [Add a voice](https://docs.tryhamsa.com/agents/voices/add-a-voice.md#audio-limits) |
| Longest file the trimmer reads, and longest recording | 10 minutes | [Add a voice](https://docs.tryhamsa.com/agents/voices/add-a-voice.md#audio-limits) |
| Cover image | JPG, JPEG or PNG, up to 5 MB | [Add a voice](https://docs.tryhamsa.com/agents/voices/add-a-voice.md#audio-limits) |
| Preview text for a new voice | At least 5 words | [Add a voice](https://docs.tryhamsa.com/agents/voices/add-a-voice.md) |
| Dictionary name | 1 to 100 characters | [Pronunciation dictionaries](https://docs.tryhamsa.com/agents/voices/dictionaries.md) |

## Policies, guardrails, functions and macros

| Limit | Value | More |
| - | - | - |
| Checks on one piece of speech | Share a budget of half a second. A check that runs out of time counts as no match. | [Policies & guardrails](https://docs.tryhamsa.com/agents/safety/policies-and-guardrails.md#how-it-works-on-a-call) |
| A function run | 50 ms | [Functions & macros](https://docs.tryhamsa.com/agents/safety/functions-and-macros.md#limits) |
| A macro run | 50 ms | [Functions & macros](https://docs.tryhamsa.com/agents/safety/functions-and-macros.md#limits) |
| Code | Up to 20,000 characters | [Functions & macros](https://docs.tryhamsa.com/agents/safety/functions-and-macros.md#limits) |
| Notes | Up to 2,000 characters | [Functions & macros](https://docs.tryhamsa.com/agents/safety/functions-and-macros.md#limits) |
| Prompt macro parameters | Up to 20, each up to 64 characters | [Functions & macros](https://docs.tryhamsa.com/agents/safety/functions-and-macros.md#limits) |
| **Try it** on a macro | Once every 3 seconds | [Functions & macros](https://docs.tryhamsa.com/agents/safety/functions-and-macros.md#limits) |

## Releases

| Limit | Value | More |
| - | - | - |
| **Change summary** | Required, up to 500 characters | [Drafts and versions](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md#publish-a-version) |
| **New version label** | Optional, up to 100 characters | [Drafts and versions](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md#publish-a-version) |
| Draft without an edit | Expires after 7 days. A draft in a merge request doesn't expire. | [Drafts and versions](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md#your-draft) |
| Discarded draft | Can be brought back for 30 days | [Drafts and versions](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md#discard-your-draft) |
| Closed or expired drafts and merge requests | Kept for 30 days | [Merge requests](https://docs.tryhamsa.com/agents/release/merge-requests.md) |
| Phone numbers per environment | One. Without deployments, one per agent. | [Phone numbers](https://docs.tryhamsa.com/agents/connect/phone-numbers.md#how-numbers-and-agents-fit-together) |

## Phone numbers

| Limit | Value | More |
| - | - | - |
| The same number in Hamsa | Can be added once, across all projects | [Phone numbers](https://docs.tryhamsa.com/agents/connect/phone-numbers.md#how-numbers-and-agents-fit-together) |
| Agents per number | One at a time | [Phone numbers](https://docs.tryhamsa.com/agents/connect/phone-numbers.md#how-numbers-and-agents-fit-together) |
| **Twilio account SID** | Starts with `AC`, followed by 32 characters | [Bring your own number](https://docs.tryhamsa.com/agents/connect/bring-your-own-number.md#add-a-twilio-number) |
| **Twilio auth token** | At least 32 characters | [Bring your own number](https://docs.tryhamsa.com/agents/connect/bring-your-own-number.md#add-a-twilio-number) |
| **Carrier IPs** (Hamsa SIP gateway) | Up to 20 IPv4 addresses or CIDR ranges | [Bring your own number](https://docs.tryhamsa.com/agents/connect/bring-your-own-number.md#the-hamsa-sip-gateway) |
| Editing a number | Not possible. Delete it and add it again. | [Phone numbers](https://docs.tryhamsa.com/agents/connect/phone-numbers.md#the-phone-numbers-page) |

## Batch calls

| Limit | Value | More |
| - | - | - |
| Recipient file | CSV or Excel, up to 50 MB | [Batch call recipient file](https://docs.tryhamsa.com/agents/connect/batch-call-file.md#limits) |
| Recipients per batch call | At least 1. No fixed maximum. | [Batch call recipient file](https://docs.tryhamsa.com/agents/connect/batch-call-file.md#limits) |
| The same phone number in one file | Once | [Batch call recipient file](https://docs.tryhamsa.com/agents/connect/batch-call-file.md#phone-number-rules) |
| Local numbers (with `ignore_e164_validation`) | Up to 13 digits | [Batch call recipient file](https://docs.tryhamsa.com/agents/connect/batch-call-file.md#phone-number-rules) |
| Concurrency per batch call | 1 up to your plan's limit, shared with every active batch call | [Batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md#concurrency) |
| Attempts per recipient | Up to 3: the first call, a retry after 10 minutes, another after 20 more minutes | [Batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md#retries) |
| Calls that are retried | Only **Failed** ones. **No answer** isn't retried automatically. | [Batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md#retries) |
| A call that never reports an end | Counted as failed after 90 minutes | [Batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md#retries) |
| How often Hamsa checks for calls to start | About once a minute | [Batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md#when-calls-go-out) |

## Webhooks

| Limit | Value | More |
| - | - | - |
| Webhook URL | Must start with `https://` | [Webhooks](https://docs.tryhamsa.com/agents/connect/webhooks.md#set-up-a-webhook) |
| Reachability check on publish (single prompt) | The URL must answer within 2 seconds | [Webhooks](https://docs.tryhamsa.com/agents/connect/webhooks.md#set-up-a-webhook) |
| Wait for your server | Up to 30 seconds | [Webhooks](https://docs.tryhamsa.com/agents/connect/webhooks.md#delivery) |
| Retries | None. Any response, `4xx` and `5xx` included, counts as delivered. | [Webhooks](https://docs.tryhamsa.com/agents/connect/webhooks.md#delivery) |
| Signature | Requests aren't signed. Check the Bearer token. | [Webhooks](https://docs.tryhamsa.com/agents/connect/webhooks.md#delivery) |

## Website widget

| Limit | Value | More |
| - | - | - |
| **Button label** | Up to 40 characters | [Embed on your website](https://docs.tryhamsa.com/agents/publishing/embed.md) |
| Logo and background image URLs | Must start with `https://` | [Embed on your website](https://docs.tryhamsa.com/agents/publishing/embed.md) |
| Your site | Must be served over HTTPS for the microphone | [Embed on your website](https://docs.tryhamsa.com/agents/publishing/embed.md#before-you-start) |

## API keys

| Limit | Value | More |
| - | - | - |
| Key name | Unique in the project, up to 100 characters | [API keys](https://docs.tryhamsa.com/overview/create-api-keys.md) |
| Header | `Authorization: Token <key>`. `Bearer` is refused with 401. | [API keys](https://docs.tryhamsa.com/overview/create-api-keys.md#use-a-key) |
| Call token | Works once, for 30 seconds | [API keys](https://docs.tryhamsa.com/overview/create-api-keys.md#from-your-server-with-a-secret-key) |
| Key expiry | Keys don't expire | [API keys](https://docs.tryhamsa.com/overview/create-api-keys.md#good-to-know) |
| Overlap when you rotate | **Right away**, **1 day**, **7 days** or **30 days**. Starts at 7 days for a public key and 1 day for a secret key. | [API keys](https://docs.tryhamsa.com/overview/create-api-keys.md#rotate-a-key) |
| Public keys | One environment each, and can only start calls | [API keys](https://docs.tryhamsa.com/overview/create-api-keys.md#which-key-do-i-need) |
| Secret keys | Refused from a browser with 403. Shown once, when created. | [API keys](https://docs.tryhamsa.com/overview/create-api-keys.md) |

## Credits

| Limit | Value | More |
| - | - | - |
| How long credits last | Twelve months from the day each batch arrives | [Billing](https://docs.tryhamsa.com/overview/billing.md#how-credits-work) |
| Which credits go first | The batch that expires soonest | [Billing](https://docs.tryhamsa.com/overview/billing.md#how-credits-work) |
| Original balance and Enterprise credits | Don't expire | [Billing](https://docs.tryhamsa.com/overview/billing.md#how-credits-work) |
| Starting a call | Needs a balance above zero. A call in progress is never cut short. | [Billing](https://docs.tryhamsa.com/overview/billing.md#when-you-run-out-of-credits) |
| API requests with no balance | Refused with `402` | [Billing](https://docs.tryhamsa.com/overview/billing.md#when-you-run-out-of-credits) |
| Usage alerts | At 90%, 95% and 100% of credits used, at most once a day each | [Billing](https://docs.tryhamsa.com/overview/billing.md#when-you-run-out-of-credits) |
| Expired credits leaving your balance | Can take up to an hour to show | [Billing](https://docs.tryhamsa.com/overview/billing.md#how-credits-work) |

## Conversation log and monitoring

| Limit | Value | More |
| - | - | - |
| Background export | Up to 1,000 calls. The download link works for 24 hours. | [Conversation log](https://docs.tryhamsa.com/agents/monitor/conversation-log.md#export-the-log) |
| Live calls board | Up to 30 calls, refreshed every 20 seconds | [Live calls](https://docs.tryhamsa.com/agents/monitor/live-calls.md) |
| "Live now" count on Analytics | Calls that started in the last 10 minutes | [Live calls](https://docs.tryhamsa.com/agents/monitor/live-calls.md#good-to-know) |
| Outcome dashboard period | Up to 1,000 days | [Outcome dashboard](https://docs.tryhamsa.com/agents/monitor/outcome-dashboard.md) |

## Related

> [card] [Troubleshooting](https://docs.tryhamsa.com/agents/reference/troubleshooting.md)
>
> What to do when you hit one of these.

> [card] [Billing](https://docs.tryhamsa.com/overview/billing.md)
>
> Plans, credits and concurrent calls.

> [card] [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md)
>
> The call settings and their ranges.

> [card] [Add to the knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/add-items.md)
>
> File types, sizes and chunking.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.