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

# Analytics API — Query Call Metrics, QA, and Insights

> Query aggregated call analytics, sentiment trends, QA scores, compliance results, and agent performance data from NeuronLens via the REST API.

The NeuronLens Analytics API gives you programmatic access to the same aggregated metrics, trend data, and compliance insights visible in the dashboard — so you can power your own BI tools, build internal dashboards, or trigger automated alerts based on QA thresholds. All analytics endpoints accept date ranges and optional grouping dimensions, and return pre-aggregated results you can render directly.

***

## Get Call Analytics

<code>GET /analytics/calls</code>

Returns aggregated call metrics across a date range. Use `group_by` to break results down by day, week, agent, campaign, or language.

### Query Parameters

<ParamField query="from" type="string" required>
  ISO 8601 date string — start of the date range (inclusive). Example: `2024-01-01`.
</ParamField>

<ParamField query="to" type="string" required>
  ISO 8601 date string — end of the date range (inclusive). Example: `2024-01-31`.
</ParamField>

<ParamField query="campaign_id" type="string">
  Limit results to calls from a specific campaign.
</ParamField>

<ParamField query="agent_id" type="string">
  Limit results to calls handled by a specific agent (for human-agent escalations and manually dialed calls).
</ParamField>

<ParamField query="language" type="string">
  Limit results to calls conducted in a specific BCP-47 language code. Example: `hi-IN`.
</ParamField>

<ParamField query="group_by" type="string">
  Dimension to group results by. When provided, the response includes a `grouped_data` array with one entry per group. Accepted values: `day`, `week`, `agent`, `campaign`, `language`.
</ParamField>

### Example Request

```bash theme={null}
curl "https://api.vinfer.ai/v1/analytics/calls?from=2024-01-01&to=2024-01-31&group_by=day" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "from": "2024-01-01",
  "to": "2024-01-31",
  "total_calls": 15842,
  "connected_calls": 10291,
  "connection_rate": 0.65,
  "avg_duration_seconds": 118,
  "sentiment_breakdown": {
    "positive": 0.48,
    "neutral": 0.31,
    "negative": 0.21
  },
  "intent_breakdown": {
    "loan_renewal_interest": 4210,
    "callback_requested": 2105,
    "not_interested": 2980,
    "complaint": 412,
    "dnd_request": 584
  },
  "avg_qa_score": 83.4,
  "grouped_data": [
    {
      "group": "2024-01-01",
      "total_calls": 512,
      "connected_calls": 331,
      "avg_duration_seconds": 112,
      "avg_qa_score": 81.2
    },
    {
      "group": "2024-01-02",
      "total_calls": 498,
      "connected_calls": 324,
      "avg_duration_seconds": 121,
      "avg_qa_score": 84.7
    }
  ]
}
```

<Note>
  When `group_by=day` or `group_by=week`, each entry in `grouped_data` includes the period start date as the `group` value. When `group_by=agent`, `campaign`, or `language`, the `group` value is the respective ID or code. Days with zero calls are included as entries with all metric values set to `0`.
</Note>

***

## Get QA Scores

<code>GET /analytics/qa</code>

Fetch QA evaluation scores for a single call or aggregated across a date range and set of filters.

### Query Parameters

<ParamField query="call_id" type="string">
  Return QA scores for a specific call. When provided, all other filters are ignored.
</ParamField>

<ParamField query="from" type="string">
  ISO 8601 date — start of range for aggregated QA scores. Required when `call_id` is not provided.
</ParamField>

<ParamField query="to" type="string">
  ISO 8601 date — end of range for aggregated QA scores. Required when `call_id` is not provided.
</ParamField>

<ParamField query="agent_id" type="string">
  Limit aggregated scores to a specific agent.
</ParamField>

<ParamField query="scorecard_id" type="string">
  Limit results to evaluations performed against a specific QA scorecard.
</ParamField>

### Example Request

```bash theme={null}
curl "https://api.vinfer.ai/v1/analytics/qa?from=2024-01-01&to=2024-01-31&agent_id=agt_001" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "calls_evaluated": 842,
  "overall_score": 85.2,
  "pass_rate": 0.78,
  "parameter_scores": [
    {
      "name": "Greeting Compliance",
      "avg_score": 9.4,
      "max_score": 10,
      "pass_rate": 0.94
    },
    {
      "name": "Product Pitch Accuracy",
      "avg_score": 16.1,
      "max_score": 20,
      "pass_rate": 0.72
    },
    {
      "name": "DND Handling",
      "avg_score": 9.8,
      "max_score": 10,
      "pass_rate": 0.98
    },
    {
      "name": "Escalation Protocol",
      "avg_score": 8.2,
      "max_score": 10,
      "pass_rate": 0.82
    }
  ]
}
```

<Tip>
  Sort `parameter_scores` by `pass_rate` ascending in your reporting layer to surface the parameters where agents most frequently fall short — these are your highest-leverage coaching opportunities.
</Tip>

***

## Get Compliance Results

<code>GET /analytics/compliance</code>

Returns compliance monitoring results — whether specific regulatory and script adherence checks passed or failed for a given call or across a date range.

### Query Parameters

<ParamField query="call_id" type="string">
  Return compliance results for a single specific call.
</ParamField>

<ParamField query="from" type="string">
  ISO 8601 date — start of date range for aggregated compliance results.
</ParamField>

<ParamField query="to" type="string">
  ISO 8601 date — end of date range for aggregated compliance results.
</ParamField>

<ParamField query="campaign_id" type="string">
  Filter compliance results to a specific campaign.
</ParamField>

<ParamField query="language" type="string">
  Filter by BCP-47 language code.
</ParamField>

### Example Request

```bash theme={null}
curl "https://api.vinfer.ai/v1/analytics/compliance?call_id=cal_9Hm3kP7qZ" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "call_id": "cal_9Hm3kP7qZ",
  "compliance_score": 92.0,
  "passed_checks": [
    "mandatory_disclosure_delivered",
    "dnd_opt_out_offered",
    "agent_identified_correctly",
    "call_recording_disclosure"
  ],
  "violations": [
    {
      "check": "call_duration_within_limit",
      "description": "Call exceeded the configured maximum duration of 120 seconds by 22 seconds.",
      "severity": "warning"
    }
  ]
}
```

<Warning>
  Compliance violations with `severity: critical` indicate regulatory requirements that were not met (e.g., DND opt-out not offered). These require immediate review. `warning` severity indicates best-practice deviations that should be monitored but are not regulatory breaches.
</Warning>

***

## Search Transcripts

<code>GET /analytics/search</code>

Full-text search across all processed call transcripts in your workspace. Returns matching transcript segments with their call context — useful for auditing, finding specific topics, or identifying calls where particular phrases were used.

### Query Parameters

<ParamField query="query" type="string" required>
  The keyword or phrase to search for. The search is case-insensitive and matches partial words. For multi-word phrases, the words must appear in proximity (within 5 seconds of each other in the transcript timeline).
</ParamField>

<ParamField query="from" type="string">
  ISO 8601 date — limit search to calls that occurred on or after this date.
</ParamField>

<ParamField query="to" type="string">
  ISO 8601 date — limit search to calls that occurred on or before this date.
</ParamField>

<ParamField query="language" type="string">
  Limit search to transcripts in a specific BCP-47 language.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of matching segments to return per page. Maximum `100`.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of results to skip for pagination.
</ParamField>

### Example Request

```bash theme={null}
curl "https://api.vinfer.ai/v1/analytics/search?query=loan+renewal&from=2024-01-01&to=2024-01-31&language=hi-IN&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "query": "loan renewal",
  "total_matches": 4210,
  "limit": 5,
  "offset": 0,
  "results": [
    {
      "call_id": "cal_9Hm3kP7qZ",
      "campaign_id": "cmp_4Rv8sT1wX",
      "timestamp": "2024-02-01T09:15:10Z",
      "speaker": "agent",
      "text": "Aapka **loan renewal** ka time aa gaya hai. Kya aap is baare mein baat karna chahenge?",
      "start_time": 7.6,
      "end_time": 13.0
    },
    {
      "call_id": "cal_3Ft7pM2wQ",
      "campaign_id": "cmp_4Rv8sT1wX",
      "timestamp": "2024-02-01T09:22:44Z",
      "speaker": "customer",
      "text": "Main **loan renewal** ke baare mein jaanna chahta hoon.",
      "start_time": 24.1,
      "end_time": 28.5
    }
  ]
}
```

<Note>
  Search results highlight the matched terms in the `text` field with markdown bold markers (`**term**`) for easy rendering in your UI. Strip the markers if you need plain text.
</Note>