> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signalmd.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect Retell
> Connect a Retell agent with an API key, keep its calls flowing in, add more agents, and replace or remove a connection.
SignalMD reads your agent and its calls from Retell's API with an API key. This page is the reference for the connection. For the short path from sign-up to your first issues, use the [Quickstart](/quickstart).
## What you need
* A Retell account with at least one agent, and an API key from the Retell dashboard's API keys page.
* A SignalMD workspace: your personal one, or an organization if you work with a team. An agent belongs to the workspace you connect it in.
Conversation flow agents and single-prompt agents both connect. Step-level issues and the flow diagram are built from the agent's steps: the nodes of a conversation flow, or the states of a single-prompt agent.
## Connect an agent
Open **Agent config** in the sidebar. A workspace with no agents of its own shows **Get started**. To add another agent, select **Add agent** at the top of **Agent config** or at the bottom of the agent menu in the sidebar.
Paste your Retell API key into **Retell key**, or pick one under **Saved key** to reuse it. Optionally give a new key a **Name**, such as the client's name. SignalMD checks the key as soon as you stop typing: "Checking the key…", then "Key accepted. 3 agents to choose from."
Pick the agent from **Agent**. Agents already connected in this workspace show **Already connected**.
Select **Connect**. SignalMD reads the configuration and asks what to import: how far back, at most how many calls, what percent of new calls to keep, and an optional cap on them. It imports them and drafts the [brief](/concepts/the-brief) from both. Approving the brief starts the analysis.
Once connected, the agent's name, Retell agent ID and current version appear under the title of **Agent config**.
The key is encrypted at rest and afterwards shown only as its name plus its last four characters, such as "Acme Health · \*\*\*\*ab5c". SignalMD uses it to read: the agent, its flow or prompt, tools, phone numbers, knowledge bases and calls. It does not use it to change anything in Retell. Two features write to Retell, both opt-in and both through a separate **Retell write key** you store for testing: test runs in Retell's simulator (see [Test a fix](/guides/test-a-fix)), and publishing a drafted fix, which happens only when an admin selects publish in [Build](/copilot/build). See [Data and security](/data-and-security#changes-to-your-retell-agent).
## How SignalMD gets data from Retell
| What SignalMD reads | When |
| - | - |
| The agent's configuration | When you connect, and again for each new version |
| A new version | Picked up within about 10 minutes of publishing |
| Your first import | When you select **Import calls** after connecting: the ended calls from the window you choose (30 days unless you change it), up to the number you choose (500 unless you change it), newest first. Analysis waits for you to approve the brief |
| New calls | Within about 15 minutes of ending. With the webhook, as soon as they end. Only the percent set in **Keep importing new calls**, up to the **Cap** |
New calls reach the board without any action from you, and their analysis follows within a few minutes. Calls SignalMD placed itself as tests are never imported.
### Import settings
On **Agent config**, **Import settings** holds what you chose for the first import, and you can change it at any time with **Save**:
* **How far back** and **At most**: what **Import again** brings in when you do not choose a window.
* **Keep importing new calls**: a percent from 0 to 100. Below 100%, calls are picked by their ID, so the same calls are kept whether they arrive by webhook or by SignalMD's own check. 0% imports no new calls.
* **Cap**: **No cap**, or a number of calls per **Day**, **Week** or **Month**. Days, weeks and months are counted in UTC, and a week starts on Monday. Once the cap is reached, new calls that end in the rest of that day, week or month are skipped, not saved for later, and importing starts again when the next one begins. Only calls that arrive on their own count towards it; **Import again** does not.
With a cap set, the panel says where it stands, such as "12 of 50 this week". When it is full, it says when new calls are imported again.
Importing is free. Analysing a call uses 1 credit per processed minute. With calls already imported, the panel estimates what new calls use a month at the percent you set, from the agent's recent calls. When the cap is lower than that, the estimate is what the cap allows, said as "at most".
### Add the webhook (optional)
The webhook makes calls arrive as soon as they end, instead of within about 15 minutes. SignalMD never sets or changes your agent's webhook field; you add it yourself.
1. On **Agent config**, copy the **Webhook URL**: `https://api.signalmd.dev/webhooks/retell`.
2. In Retell, paste it into the agent's webhook URL, with the `call_ended` or `call_analyzed` event turned on.
3. Make sure SignalMD is connected with the API key that your Retell workspace marks for webhooks. Retell signs each delivery with that key, and SignalMD refuses a delivery signed by any other key with `401`. If you connected with a different key, use **Replace key** (below).
The same panel shows **Last call arrived** and when the last webhook arrived ("No webhook received yet" until one does). If the agent already sends its webhook to another service, you can leave it: new calls still show up within about 15 minutes without it.
If Retell refuses the stored key, that panel shows the reason. Connecting a working key clears it.
## Import calls
You rarely need to import by hand after the first import. To bring in an older window, or calls from a version at once, use the panel on **Agent config**, titled **Import more calls** once calls exist:
* **Import again** uses your import settings: the last 30 days and up to 500 new calls unless you changed them.
* **Choose a window and count** lets you set **From** and **To** (call start dates) and **Calls to add**, then **Import again**.
The panel says before you start how far back an import may reach, how many calls one import takes, and how many more calls your plan's credits cover before its period resets. Then:
* **Safe to repeat.** Calls already imported are skipped and do not count towards **Calls to add**. When the whole window is stored, the progress says "No new calls: everything in this window was already imported."
* **Limits.** An import reaches back at most 30 days and brings in at most 1,000 calls. Ask for more and it is trimmed, with a note such as "Imported 1,000 of 1,500 requested; one import brings in up to 1,000 calls. Import again for more."
* **Plan credits.** Calls that run past your plan's credits are stored and wait for analysis until the period resets or you upgrade. See [Pricing](/billing/pricing).
* **Failures.** SignalMD retries on its own. If it still fails, the page says "The import stopped." with the reason and an **Import again** button.
## Connect more than one agent
Each Retell agent you connect becomes its own agent in SignalMD, with its own brief, calls, issues, flow and versions. Switch between them with the agent menu in the sidebar; the demo agent is marked "(demo)". A saved key can serve many agents, and **New key** adds another Retell workspace's key. Your plan sets how many agents a workspace can hold.
## Disconnect and delete
Only workspace admins see these actions, in the **Connection** panel on **Agent config**.
* **Replace key.** After you rotate the key in Retell, or to switch to the key marked for webhooks, select **Replace key**. The new key must be able to read this agent.
* **Delete agent.** SignalMD lists what goes, with counts: calls with their transcripts, traces and analysis, issues, the brief, captured versions, tests and runs, and the stored Retell key unless another agent uses it. Deleting cannot be undone, and nothing changes in Retell.
* **Cut off access.** Delete or replace the API key in Retell. New calls and imports for that agent then stop until a working key is connected.
SignalMD stores each call's full record as Retell sent it, so improvements to its analysis reach your existing calls without importing again. Deleting your organization, or your account for a personal workspace, erases everything SignalMD stored for it. What is stored, who processes it and how deletion works are in [Data and security](/data-and-security).
## Troubleshooting
Retell returned an authorisation error. Copy the key again from the API keys page in Retell, with no spaces, and check it comes from the Retell workspace that holds the agent.
The agent may have been deleted in Retell, or it belongs to another Retell workspace. Use that workspace's key, or choose another agent.
Retell returned an error (the number is its status code) or no answer arrived. Select **Try again**. These are not problems with your key.
Create an agent in Retell, then select **Check again**.
Choose the agent from the agent menu in the sidebar. If you cannot see it, check the organization switcher: it may be in another workspace.
A call can take up to about 15 minutes to arrive without the webhook, plus a few minutes for its analysis. On **Agent config**, **Last call arrived** says when SignalMD last stored one, and an error under it says if Retell is refusing the key. Only ended calls count, and calls made by other agents are not imported: compare the Retell agent ID under the page title with the one in Retell. To pull calls in at once, use **Import more calls**.
Calls are matched on their start date. Select **Choose a window and count** and widen **From** and **To**, up to 30 days back.
Check that the URL in the agent's webhook field in Retell matches the one on **Agent config**, that the events include call ended or call analyzed, and that SignalMD is connected with the key marked for webhooks.
The page shows the reason, after SignalMD has already retried on its own. Select **Import again** or **Analyze again**. If it fails again with a Retell error, check that the key still works.
You are on the shared demo. Select **Connect your agent** in the banner.
## Next steps
What to check before you approve.
Act on the first issue on your board.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.