Insights

Insights (also accepted as goals for backward compatibility) let you define measurable targets — such as lead capture rate or booking completion — and track them against your genies’ conversations.

Standard users can only manage their own insights. Admin users can view and manage all insights by passing adminMode: true.

List all insights

Returns all insights with full details for the authenticated user.

string

required

Must be "insights"

string

required

Must be "all"

object

Show properties

number

default:"50"

Results per page. Maximum 500.

number

default:"0"

Number of results to skip.

boolean

default:"false"

Admin only. When true, returns insights across all users.

string

Admin only. Return insights owned by this user ID.

object

Show properties

string

Filter to insights attached to a specific genie.

boolean

object

Show properties

object[]

Array of insight objects.

number

List insights

Returns a paginated list of insights for the authenticated user.

string

required

Must be "insights"

string

required

Must be "list"

object

Show properties

string

Filter insights by name (case-insensitive).

number

default:"50"

Results per page. Maximum 500.

number

default:"0"

Number of results to skip.

boolean

default:"false"

Admin only. When true, returns insights across all users.

string

Admin only. Return insights owned by this user ID.

boolean

object

Show properties

object[]

Array of insight objects.

number

Get insight

Retrieves a single insight by ID.

string

required

Must be "insights"

string

required

Must be "get"

string

required

The insight UUID.

object

Show properties

boolean

default:"false"

Admin only. When true, allows fetching insights owned by other users.

Create insight

Creates a new insight metric.

string

required

Must be "insights"

string

required

Must be "create"

object

required

Show properties

string

required

Insight name (e.g. "Lead capture rate").

string

A short description of what this insight measures.

object[]

Array of field definitions that make up this insight’s tracked metrics.

boolean

When true, marks this insight as a default template that appears as a starting point for new insights.

string

Admin only. Create the insight on behalf of this user instead of the caller.

boolean

object

Show properties

object

The created insight object.

const response = await ApiService.invoke({
  resource: "insights",
  action: "create",
  data: {
    name: "Lead capture rate",
    description: "Percentage of conversations that result in a captured lead",
    fields: [
      { label: "Leads captured", key: "leads_captured" }
    ],
    is_default: false,
  },
});

curl -X POST https://api.helpgenie.ai/v1/insights \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "insights",
    "action": "create",
    "data": {
      "name": "Lead capture rate",
      "description": "Percentage of conversations that result in a captured lead",
      "fields": [{ "label": "Leads captured", "key": "leads_captured" }],
      "is_default": false
    }
  }'

Update insight

Updates an existing insight. Supports partial updates — send only the fields you want to change.

string

required

Must be "insights"

string

required

Must be "update"

string

required

The insight ID. Must be numeric — a non-numeric value returns VALIDATION_ERROR.

object

Show properties

string

New insight name.

string

New description of what this insight measures.

object[]

Replacement array of field definitions for this insight’s tracked metrics.

boolean

When true, marks this insight as a default template that appears as a starting point for new insights.

boolean

default:"false"

Admin only. When true, allows updating insights owned by other users and includes the owner profile in the response.

Only name, description, fields, and is_default are applied. If data contains none of them — for example when it carries only unrelated keys — nothing is written and the insight is returned unchanged, with the same response shape as a successful update.

boolean

object

Show properties

object

The updated insight.

Show properties

number

Insight ID.

string | null

Insight name.

string | null

Insight description.

object[] | null

Field definitions for the tracked metrics.

boolean | null

Whether this insight is a default template.

string

ISO 8601 creation timestamp.

object[]

Genies this insight is attached to. Omitted when there are none.

Show item properties

string

Genie ID.

string

Genie name.

object

Owner profile — present only when adminMode is true.

Show properties

string

User ID.

string

Full name.

string

Email address.

object

The same object as insight, kept for backward compatibility.

const response = await ApiService.invoke({
  resource: "insights",
  action: "update",
  id: "42",
  data: {
    name: "Lead capture rate",
    is_default: true,
  },
});

curl -X POST https://api.helpgenie.ai/v1/insights \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "insights",
    "action": "update",
    "id": "42",
    "data": {
      "name": "Lead capture rate",
      "is_default": true
    }
  }'

{
  "success": true,
  "data": {
    "insight": {
      "id": 42,
      "name": "Lead capture rate",
      "description": "Percentage of conversations that result in a captured lead",
      "fields": [{ "label": "Leads captured", "key": "leads_captured" }],
      "is_default": true,
      "created_at": "2024-01-15T10:30:00.000Z"
    },
    "goal": {
      "id": 42,
      "name": "Lead capture rate",
      "description": "Percentage of conversations that result in a captured lead",
      "fields": [{ "label": "Leads captured", "key": "leads_captured" }],
      "is_default": true,
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  }
}

Delete insight

Permanently deletes an insight.

string

required

Must be "insights"

string

required

Must be "delete"

string

required

The insight UUID.

This action is irreversible.

Attach insight to genie

Links an insight to a genie. Each genie can have only one insight attached at a time — attaching a new one replaces the existing attachment.

string

required

Must be "insights"

string

required

Must be "attach"

object

required

Show properties

string

required

UUID of the genie to attach the insight to.

string

required

UUID of the insight to attach. Also accepted as goalId for backward compatibility.

boolean

await ApiService.invoke({
  resource: "insights",
  action: "attach",
  data: {
    agentId: "agent-uuid",
    insightId: "insight-uuid",
  },
});

curl -X POST https://api.helpgenie.ai/v1/insights \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "insights",
    "action": "attach",
    "data": {
      "agentId": "agent-uuid",
      "insightId": "insight-uuid"
    }
  }'

Detach insight from genie

Removes the insight attachment from a genie.

string

required

Must be "insights"

string

required

Must be "detach"

object

required

Show properties

string

required

UUID of the genie to detach the insight from.

Generate insight

Uses language understanding to suggest insight fields from a natural-language description. Returns suggested name, description, type, and target values that can be reviewed before saving.

string

required

Must be "insights"

string

required

Must be "generate"

object

required

Show properties

string

required

Natural-language description of the insight to generate (e.g. "Track how often callers book an appointment").

object

Optional context about the genie to improve suggestion quality.

Show properties

string

Genie name.

string

Genie description.

string

Genie’s primary purpose.

string

Genie’s system prompt.

boolean

object

Show properties

string

Suggested insight name.

string

Suggested description.

string

Suggested insight type.

number

Suggested target value.

const result = await ApiService.invoke({
  resource: "insights",
  action: "generate",
  data: {
    description: "Track how often callers book an appointment",
    genieContext: {
      name: "Booking Bot",
      purpose: "Appointment scheduling",
    },
  },
});

Error codes

Code	Meaning
`VALIDATION_ERROR`	Missing or invalid required parameter
`NOT_FOUND`	Insight not found
`FORBIDDEN`	Access denied
`INTERNAL_ERROR`	Unexpected server error

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

List all insights

List insights

Get insight

Create insight

Update insight

Delete insight

Attach insight to genie

Detach insight from genie

Generate insight

Error codes

​List all insights

​List insights

​Get insight

​Create insight

​Update insight

​Delete insight

​Attach insight to genie

​Detach insight from genie

​Generate insight

​Error codes

List all insights

List insights

Get insight

Create insight

Update insight

Delete insight

Attach insight to genie

Detach insight from genie

Generate insight

Error codes