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

# Best Practices & Troubleshooting

> Get better reports, fix common problems, and check the defaults

## Best practices

| Practice                                       | Why                                                                                                                        |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Name metrics descriptively                     | The analysis reasons about the metric by its name. `Conversion Rate` guides it; `metric_2` does not.                       |
| Keep endpoint parameters minimal               | Send only what is needed to fetch the value. Fewer parameters mean fewer failure modes and faster runs.                    |
| Test the cURL before saving                    | The generated Dummy cURL is the exact request Callkaro will send. Confirming it works now avoids an empty report tomorrow. |
| Be specific in the RCA prompt                  | Scope, exclusions and priority are what separate a useful report from a generic one.                                       |
| Exclude known artefacts explicitly             | Telling it to ignore sub-5-second disconnects stops the analysis spending its attention on dialer noise.                   |
| Set targets you have actually achieved         | An unrealistic target produces daily reports about a gap that has no fix — and the analysis will eventually tell you so.   |
| Return a diagnostic string from Python sources | A short message alongside the number gives the analysis context it cannot get from the number alone.                       |
| Work the board, not just the reports           | Moving cards through the columns is what lets the next report tell you whether the fix worked.                             |
| Read before you assign                         | Every fix is reviewable for a reason. Check the evidence and the prompt excerpt before sending anything to AI FDE.         |

## Troubleshooting

<AccordionGroup>
  <Accordion title="No report was generated for a day">
    Either every metric met its target, the shortfall was under 1 percentage point, the RCA prompt did not cover the metric that missed, or Auto RCA is off. Open the day-wise timeline — it states which of these applied.
  </Accordion>

  <Accordion title="A metric shows as &#x22;could not be measured&#x22;">
    No value came back from its data source for that day. Check the timeline entry for the endpoint or Python source, and verify the **Source** path on the metric matches the field the source actually returns.
  </Accordion>

  <Accordion title="The metric value is always empty">
    Almost always a referencing mistake. API sources need the extra `.data` segment; Python sources do not. Compare your Source field against the response shape.
  </Accordion>

  <Accordion title="An endpoint was &#x22;partly delivered&#x22;">
    The batch was split and some parts failed. The timeline shows how many calls were processed and how many were not, along with the status codes returned.
  </Accordion>

  <Accordion title="&#x22;Save the agent first&#x22; appears">
    Data sources are configured against a saved agent. Save the agent, then return to the KPI Manager tab.
  </Accordion>

  <Accordion title="The report says data was insufficient">
    There were too few audited calls that day to conclude anything reliably. This is stated deliberately rather than guessed around. Widen the scope in your RCA prompt, or wait for a higher-volume day.
  </Accordion>

  <Accordion title="The same cause keeps appearing">
    It will be flagged as **recurring** with its first-observed date. Check the Pending Tasks board — the fix may never have been assigned, or may have been rolled out to only part of your traffic.
  </Accordion>

  <Accordion title="I changed the config but the report looks the same">
    Changes apply to the next run, not to reports already generated. Use Run Manual RCA if you need to see the effect immediately.
  </Accordion>

  <Accordion title="I want analysis on one metric only">
    Say so in the RCA prompt. Other metrics stay measured and charted, but will not trigger an analysis.
  </Accordion>
</AccordionGroup>

## Defaults and limits

| Setting                                   | Default                                                          |
| ----------------------------------------- | ---------------------------------------------------------------- |
| Automatic run time                        | 5:00 AM IST daily, covering the previous calendar day            |
| Shortfall required to trigger an analysis | 1.0 percentage point below target                                |
| Auto RCA                                  | On for every agent                                               |
| Default RCA model                         | GPT-5.4                                                          |
| RCA prompt maximum length                 | 10,000 characters                                                |
| Built-in metric                           | `connected_to_conversion_percentage`, calculated by the platform |
| Dashboard default date range              | The last 7 days                                                  |
| Recurrence history window                 | Recent reports from the past 14 days                             |
| Automatic handoff of fixes to AI FDE      | Off — fixes are assigned by a person                             |
| Report email                              | Sent to the agent owner whenever a report is generated           |

## Access

| Action                                      | Permission required |
| ------------------------------------------- | ------------------- |
| View the KPI Manager Dashboard              | Analytics — View    |
| View an agent's KPI Manager configuration   | Agents — View       |
| Save configuration or run a manual RCA      | Agents — Create     |
| Delete an agent's KPI Manager configuration | Agents — Delete     |

<Tip>
  **In-product help.** The **Guide** button in the KPI Manager header opens a short quick-start reference inside the product, covering the same setup steps in condensed form.
</Tip>