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

# Insights

> Derived outcome signals and the 'needs attention' feed — powering the Activity page summary tiles and prioritised action list.

Insights aggregate conversation data into actionable signals. All data covers a rolling 7-day window. Workspace members have access to the same scope as their workspace owner.

***

## Actions

### `weekly-summary`

Returns a high-level summary of the past 7 days compared to the previous 7-day window. Powers the four summary tiles at the top of the Activity page.

**Parameters**

| Field       | Type    | Required | Description                             |
| ----------- | ------- | -------- | --------------------------------------- |
| `adminMode` | boolean | No       | Admin only — aggregate across all users |
| `userId`    | string  | No       | Admin only — scope to a specific user   |

**Response**

```json theme={null}
{
  "conversations": {
    "current": 42,
    "previous": 35,
    "delta": 20
  },
  "leads": {
    "current": 8,
    "previous": 6,
    "delta": 33
  },
  "afterHours": {
    "current": 11
  },
  "attention": {
    "current": 5,
    "escalations": 2,
    "lowSentiment": 2,
    "negativeFeedback": 1
  },
  "silentGenies": {
    "current": 1,
    "total": 4
  },
  "window": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-08T00:00:00Z"
  }
}
```

`delta` is the integer percentage change from the previous to the current window, or `null` if there is no previous data.

`afterHours.current` is the number of conversations in the window that occurred outside business hours (before 8 am, after 6 pm, or on a weekend), calculated in the account owner's timezone. Returns `null` when the account timezone is not configured.

`leads` is retained for API compatibility. The leads feature is being retired and `leads` will be removed in a future release — do not build new integrations against it.

***

### `needs-attention`

Returns a prioritised feed of items that require action — escalations, low-sentiment conversations, negative feedback, and Genies with no recent conversations. Up to 10 items per bucket, covering the last 7 days.

**Parameters**

| Field       | Type    | Required | Description |
| ----------- | ------- | -------- | ----------- |
| `adminMode` | boolean | No       | Admin only  |
| `userId`    | string  | No       | Admin only  |

**Response**

```json theme={null}
{
  "escalations": [
    {
      "id": "detail-id",
      "conversationId": "conv-id",
      "agentId": "agent-uuid",
      "agentName": "Support Genie",
      "agentBranding": null,
      "summary": "Caller requested human escalation.",
      "occurredAt": "2024-01-07T10:00:00Z",
      "reason": "requested_human"
    }
  ],
  "lowSentiment": [
    {
      "id": "detail-id",
      "conversationId": "conv-id",
      "agentId": "agent-uuid",
      "agentName": "Support Genie",
      "agentBranding": null,
      "summary": "Caller was frustrated with the response.",
      "score": 0.21,
      "occurredAt": "2024-01-07T11:00:00Z"
    }
  ],
  "negativeFeedback": [
    {
      "id": "feedback-id",
      "conversationId": "conv-id",
      "agentId": "agent-uuid",
      "agentName": "Support Genie",
      "agentBranding": null,
      "feedbackText": "Didn't answer my question.",
      "occurredAt": "2024-01-07T12:00:00Z"
    }
  ],
  "silentGenies": [
    {
      "agentId": "agent-uuid",
      "agentName": "Onboarding Genie",
      "agentBranding": null,
      "createdAt": "2023-12-01T00:00:00Z"
    }
  ],
  "threshold": 0.4,
  "window": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-08T00:00:00Z"
  }
}
```

`threshold` is the sentiment score below which a conversation is classified as low sentiment.

***

## Error codes

| Code             | Meaning                 |
| ---------------- | ----------------------- |
| `INTERNAL_ERROR` | Unexpected server error |