> For the complete documentation index, see [llms.txt](https://docs.arcade.software/kb/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.arcade.software/kb/leverage/advanced-features/rest-api/insights-api.md).

# Insights API

## Arcade Insights API (Public)

This document describes Arcade's insights endpoints for customers who want to access flow analytics data programmatically.

### Base URL

<https://api.arcade.software/insights>

makefile Copy code

### Authentication

#### How do I authenticate with the API?

All requests must include your Arcade **API key** in the `Authorization` header.

#### Generate an API key

1. Go to **Settings > Advanced** in your Workspace settings.
2. Select **Generate a new API key**.
3. In the modal:
   * The Insights API key does not require `provisioning` scope.

#### Example

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "plays", "teamId": "TEAM_ID", "flowId": "FLOW_ID", "from": "2025-01-01T00:00:00.000Z", "to": "2025-01-20T23:59:59.000Z"}' \
  https://api.arcade.software/insights
```

### Requirements & Limits

* **Plan requirement**: the API key must belong to a workspace on the Enterprise only.&#x20;

#### Rate Limiting

100 requests per minute per IP

### Error Responses (Common)

All responses are JSON.

**401 Unauthorized**

```json
{ "error": "Missing authorization header" }
```

```json
{ "error": "Invalid API key" }
```

```json
{ "error": "Workspace is not growth or above" }
```

**403 Forbidden**

```json
{ "success": false, "error": "This operation requires insights scope" }
```

**400 Bad Request**

```json
{ "success": false, "errors": [...] }
```

**5xx Server Errors**

```json
{ "success": false, "error": "..." }
```

***

### Request Format

All insights endpoints use `POST` method with a JSON body. The `type` field specifies which insight to retrieve.

```json
{
  "type": "<endpoint-type>",
  "teamId": "TEAM_ID",
  "...other-parameters": "value"
}
```

#### Common Parameters

| Parameter               | Type              | Required | Description                                                   |
| ----------------------- | ----------------- | -------- | ------------------------------------------------------------- |
| `type`                  | string            | Yes      | The insight type (e.g., `plays`, `views`)                     |
| `teamId`                | string            | Yes      | Your team ID                                                  |
| `flowId`                | string            | Varies   | Flow ID (required for flow-level insights)                    |
| `from`                  | ISO 8601 datetime | Yes      | Start date (e.g., `2025-01-01T00:00:00.000Z`)                 |
| `to`                    | ISO 8601 datetime | Yes      | End date (e.g., `2025-01-20T23:59:59.000Z`)                   |
| `excludeInternalViewer` | boolean           | No       | Exclude internal viewers from results                         |
| `compareToPrevious`     | boolean           | No       | Include comparison with the previous period of equal duration |

***

### Filtering Teams by Slug via the Arcade API

Each team in Arcade has a **stable slug** that appears in the workspace URL.

**Example URL structure:**

```
https://app.arcade.software/workspaces/<WORKSPACE_ID>/teams/<SLUG>/arcades
```

You can use this slug to identify and retrieve a specific team from the `/teams` API response.

***

#### Fetch a Team by Slug

Since the `/teams` endpoint returns all teams, you can filter the response using `jq`.

**Example: retrieve the team with slug `my-team`:**

```bash
curl -sS \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  https://api.arcade.software/teams \
| jq '.. | arrays | .[] | select(.slug? == "my-team")'
```

***

### Flow Insights

#### Plays

Returns plays, completions, and CTA clicks for a flow.

**Type:** `plays`

**Request Body**

```json
{
  "type": "plays",
  "teamId": "TEAM_ID",
  "flowId": "FLOW_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z",
  "excludeInternalViewer": false,
  "compareToPrevious": false
}
```

**Example**

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "plays",
    "teamId": "arcade.software",
    "flowId": "a1TnymdQA55FzIrS2AyV",
    "from": "2025-12-01T00:00:00.000Z",
    "to": "2026-01-20T23:59:59.000Z"
  }' \
  https://api.arcade.software/insights
```

**Response (200)**

```json
{
  "players": 150,
  "plays": 245,
  "completers": 120,
  "completions": 180,
  "anyCtaClickers": 85,
  "anyCtaClicks": 102,
  "finalCtaClickers": 65,
  "finalCtaClicks": 78
}
```

**Response with `compareToPrevious: true`**

```json
{
  "players": 150,
  "plays": 245,
  "completers": 120,
  "completions": 180,
  "anyCtaClickers": 85,
  "anyCtaClicks": 102,
  "finalCtaClickers": 65,
  "finalCtaClicks": 78,
  "previous": {
    "players": 130,
    "plays": 210,
    "completers": 100,
    "completions": 155,
    "anyCtaClickers": 70,
    "anyCtaClicks": 88,
    "finalCtaClickers": 55,
    "finalCtaClicks": 62
  }
}
```

***

#### Views

Returns unique viewers for a flow.

**Type:** `views`

**Request Body**

```json
{
  "type": "views",
  "teamId": "TEAM_ID",
  "flowId": "FLOW_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z",
  "excludeInternalViewer": false,
  "compareToPrevious": false
}
```

**Example**

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "views",
    "teamId": "TEAM_ID",
    "flowId": "FLOW_ID",
    "from": "2025-01-01T00:00:00.000Z",
    "to": "2025-01-20T23:59:59.000Z"
  }' \
  https://api.arcade.software/insights
```

**Response (200)**

```json
{
  "viewers": 342
}
```

**Response with `compareToPrevious: true`**

```json
{
  "viewers": 342,
  "viewersPrevious": 285
}
```

***

#### Dropoff

Returns step dropoff analysis for a flow.

**Type:** `dropoff`

**Request Body**

```json
{
  "type": "dropoff",
  "teamId": "TEAM_ID",
  "flowId": "FLOW_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z",
  "excludeInternalViewer": false
}
```

**Example**

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "dropoff",
    "teamId": "TEAM_ID",
    "flowId": "FLOW_ID",
    "from": "2025-01-01T00:00:00.000Z",
    "to": "2025-01-20T23:59:59.000Z"
  }' \
  https://api.arcade.software/insights
```

**Response (200)**

```json
[
  {
    "stepId": "step_abc123",
    "reached": 245,
    "droppedOff": 45,
    "transitions": {
      "step_def456": 180,
      "step_ghi789": 20
    }
  },
  {
    "stepId": "step_def456",
    "reached": 180,
    "droppedOff": 30,
    "transitions": {
      "step_jkl012": 150
    }
  }
]
```

***

#### Play Time

Returns average play time for a flow.

**Type:** `playTime`

**Request Body**

```json
{
  "type": "playTime",
  "teamId": "TEAM_ID",
  "flowId": "FLOW_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z",
  "excludeInternalViewer": false,
  "compareToPrevious": false
}
```

**Example**

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "playTime",
    "teamId": "TEAM_ID",
    "flowId": "FLOW_ID",
    "from": "2025-01-01T00:00:00.000Z",
    "to": "2025-01-20T23:59:59.000Z"
  }' \
  https://api.arcade.software/insights
```

**Response (200)**

```json
{
  "avgPlayTimeSeconds": 45.7
}
```

**Response with `compareToPrevious: true`**

```json
{
  "avgPlayTimeSeconds": 45.7,
  "previous": {
    "avgPlayTimeSeconds": 42.3
  }
}
```

***

#### Companies

Returns companies that viewed a flow (via IP-based identification).

**Type:** `companies`

**Request Body**

```json
{
  "type": "companies",
  "teamId": "TEAM_ID",
  "flowId": "FLOW_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z"
}
```

**Example**

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "companies",
    "teamId": "TEAM_ID",
    "flowId": "FLOW_ID",
    "from": "2025-01-01T00:00:00.000Z",
    "to": "2025-01-20T23:59:59.000Z"
  }' \
  https://api.arcade.software/insights
```

**Response (200)**

```json
[
  {
    "id": "company_abc123",
    "name": "Acme Corporation",
    "domain": "acme.com",
    "logo": "https://logo.clearbit.com/acme.com",
    "industry": "Technology",
    "employeeRange": "501-1000",
    "city": "San Francisco",
    "state": "California",
    "country": "United States",
    "estimatedAnnualRevenue": "$50M-$100M",
    "linkedin": "https://linkedin.com/company/acme",
    "twitter": "https://twitter.com/acme",
    "facebook": "https://facebook.com/acme",
    "crunchbase": "https://crunchbase.com/organization/acme",
    "playCount": 12,
    "ips": ["192.168.1.1", "192.168.1.2"],
    "role": "Engineering",
    "seniority": "Manager",
    "normalizedScore": 0.85
  },
  {
    "id": "company_def456",
    "name": "TechCorp Inc",
    "domain": "techcorp.io",
    "logo": "https://logo.clearbit.com/techcorp.io",
    "industry": "Software",
    "employeeRange": "51-200",
    "city": "Austin",
    "state": "Texas",
    "country": "United States",
    "estimatedAnnualRevenue": "$10M-$50M",
    "linkedin": "https://linkedin.com/company/techcorp",
    "twitter": null,
    "facebook": null,
    "crunchbase": null,
    "playCount": 8,
    "ips": ["10.0.0.1"],
    "role": "Product",
    "seniority": "Director",
    "normalizedScore": 0.72
  }
]
```

***

### Custom Link Insights

#### Views by Custom Link

Returns unique views grouped by custom link ID.

**Type:** `viewsByCustomLinkId`

**Request Body**

```json
{
  "type": "viewsByCustomLinkId",
  "teamId": "TEAM_ID",
  "flowId": "FLOW_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z",
  "excludeInternalViewer": false
}
```

**Example**

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "viewsByCustomLinkId",
    "teamId": "TEAM_ID",
    "flowId": "FLOW_ID",
    "from": "2025-01-01T00:00:00.000Z",
    "to": "2025-01-20T23:59:59.000Z"
  }' \
  https://api.arcade.software/insights
```

**Response (200)**

```json
[
  {
    "customLinkId": "link_abc123",
    "viewers": 85,
    "lastViewedDate": "2025-01-19T14:32:00.000Z"
  },
  {
    "customLinkId": null,
    "viewers": 257,
    "lastViewedDate": "2025-01-20T09:15:00.000Z"
  }
]
```

***

#### Plays by Custom Link

Returns plays grouped by custom link ID.

**Type:** `playsByCustomLinkId`

**Request Body**

```json
{
  "type": "playsByCustomLinkId",
  "teamId": "TEAM_ID",
  "flowId": "FLOW_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z",
  "excludeInternalViewer": false
}
```

**Example**

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "playsByCustomLinkId",
    "teamId": "TEAM_ID",
    "flowId": "FLOW_ID",
    "from": "2025-01-01T00:00:00.000Z",
    "to": "2025-01-20T23:59:59.000Z"
  }' \
  https://api.arcade.software/insights
```

**Response (200)**

```json
[
  {
    "customLinkId": "link_abc123",
    "players": 45,
    "plays": 62,
    "completers": 38,
    "completions": 48,
    "anyCtaClickers": 25,
    "anyCtaClicks": 30,
    "finalCtaClickers": 20,
    "finalCtaClicks": 22
  },
  {
    "customLinkId": null,
    "players": 105,
    "plays": 183,
    "completers": 82,
    "completions": 132,
    "anyCtaClickers": 60,
    "anyCtaClicks": 72,
    "finalCtaClickers": 45,
    "finalCtaClicks": 56
  }
]
```

***

#### Play Time by Custom Link

Returns average play time grouped by custom link ID.

**Type:** `playTimeByCustomLinkId`

**Request Body**

```json
{
  "type": "playTimeByCustomLinkId",
  "teamId": "TEAM_ID",
  "flowId": "FLOW_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z",
  "excludeInternalViewer": false
}
```

**Example**

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "playTimeByCustomLinkId",
    "teamId": "TEAM_ID",
    "flowId": "FLOW_ID",
    "from": "2025-01-01T00:00:00.000Z",
    "to": "2025-01-20T23:59:59.000Z"
  }' \
  https://api.arcade.software/insights
```

**Response (200)**

```json
[
  {
    "customLinkId": "link_abc123",
    "avgPlayTimeSeconds": 52.3
  },
  {
    "customLinkId": null,
    "avgPlayTimeSeconds": 41.8
  }
]
```

***

#### Authenticated Views

Returns authenticated viewer details for a flow.

**Type:** `authenticatedViews`

**Request Body**

```json
{
  "type": "authenticatedViews",
  "teamId": "TEAM_ID",
  "flowId": "FLOW_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z",
  "customLinkIds": ["link_abc123", "link_def456"],
  "excludeInternalViewer": false
}
```

**Example**

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "authenticatedViews",
    "teamId": "TEAM_ID",
    "flowId": "FLOW_ID",
    "from": "2025-01-01T00:00:00.000Z",
    "to": "2025-01-20T23:59:59.000Z",
    "customLinkIds": ["link_abc123"]
  }' \
  https://api.arcade.software/insights
```

**Response (200)**

```json
[
  {
    "email": "jane.doe@acme.com",
    "userName": "Jane Doe",
    "userPhotoURL": "https://example.com/photo.jpg",
    "companyName": "Acme Corporation",
    "companyLogo": "https://logo.clearbit.com/acme.com",
    "lastViewedDate": "2025-01-19T14:32:00.000Z",
    "completed": true
  },
  {
    "email": "john.smith@techcorp.io",
    "userName": "John Smith",
    "userPhotoURL": null,
    "companyName": "TechCorp Inc",
    "companyLogo": "https://logo.clearbit.com/techcorp.io",
    "lastViewedDate": "2025-01-18T10:15:00.000Z",
    "completed": false
  }
]
```

***

### Team Insights

#### Total Plays

Returns total plays, completions, and CTA clicks for an entire team.

**Type:** `totalPlays`

**Plan Required:** Pro

**Request Body**

```json
{
  "type": "totalPlays",
  "teamId": "TEAM_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z",
  "excludeInternalViewer": false,
  "compareToPrevious": false,
  "folderIds": [],
  "tagIds": []
}
```

**Example**

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "totalPlays",
    "teamId": "TEAM_ID",
    "from": "2025-01-01T00:00:00.000Z",
    "to": "2025-01-20T23:59:59.000Z"
  }' \
  https://api.arcade.software/insights
```

**Response (200)**

```json
{
  "players": 1250,
  "plays": 2450,
  "completers": 980,
  "completions": 1680,
  "anyCtaClickers": 620,
  "anyCtaClicks": 845,
  "finalCtaClickers": 480,
  "finalCtaClicks": 590,
  "previous": {
    "players": 1100,
    "plays": 2100,
    "completers": 850,
    "completions": 1450,
    "anyCtaClickers": 540,
    "anyCtaClicks": 720,
    "finalCtaClickers": 410,
    "finalCtaClicks": 505
  }
}
```

***

#### Overview Plays

Returns plays per flow for a team.

**Type:** `overviewPlays`

**Plan Required:** Pro

**Request Body**

```json
{
  "type": "overviewPlays",
  "teamId": "TEAM_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z",
  "excludeInternalViewer": false,
  "compareToPrevious": false,
  "page": 1,
  "size": 20,
  "folderIds": [],
  "tagIds": []
}
```

**Example**

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "overviewPlays",
    "teamId": "TEAM_ID",
    "from": "2025-01-01T00:00:00.000Z",
    "to": "2025-01-20T23:59:59.000Z",
    "page": 1,
    "size": 2
  }' \
  https://api.arcade.software/insights
```

**Response (200)**

```json
[
  {
    "flowId": "flow_abc123",
    "flowName": "Product Onboarding",
    "players": 450,
    "plays": 680,
    "completers": 380,
    "completions": 520,
    "anyCtaClickers": 220,
    "anyCtaClicks": 285,
    "finalCtaClickers": 175,
    "finalCtaClicks": 210,
    "previous": {
      "players": 400,
      "plays": 600,
      "completers": 340,
      "completions": 460,
      "anyCtaClickers": 195,
      "anyCtaClicks": 250,
      "finalCtaClickers": 155,
      "finalCtaClicks": 185
    }
  },
  {
    "flowId": "flow_def456",
    "flowName": "Feature Walkthrough",
    "players": 320,
    "plays": 485,
    "completers": 275,
    "completions": 390,
    "anyCtaClickers": 165,
    "anyCtaClicks": 210,
    "finalCtaClickers": 130,
    "finalCtaClicks": 155,
    "previous": {
      "players": 290,
      "plays": 430,
      "completers": 245,
      "completions": 345,
      "anyCtaClickers": 145,
      "anyCtaClicks": 185,
      "finalCtaClickers": 115,
      "finalCtaClicks": 138
    }
  }
]
```

***

#### Play Time by Team

Returns average play time for an entire team.

**Type:** `playTimeByTeam`

**Plan Required:** Pro

**Request Body**

```json
{
  "type": "playTimeByTeam",
  "teamId": "TEAM_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z",
  "excludeInternalViewer": false,
  "compareToPrevious": false,
  "folderIds": [],
  "tagIds": []
}
```

**Example**

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "playTimeByTeam",
    "teamId": "TEAM_ID",
    "from": "2025-01-01T00:00:00.000Z",
    "to": "2025-01-20T23:59:59.000Z"
  }' \
  https://api.arcade.software/insights
```

**Response (200)**

```json
{
  "avgPlayTimeSeconds": 48.5,
  "previous": {
    "avgPlayTimeSeconds": 44.2
  }
}
```

***

#### Companies for Leads

Returns companies that played flows for a team with detailed engagement metrics.

**Type:** `companiesForLeads`

**Plan Required:** Pro

**Request Body**

```json
{
  "type": "companiesForLeads",
  "teamId": "TEAM_ID"
}
```

**Example**

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "companiesForLeads",
    "teamId": "TEAM_ID"
  }' \
  https://api.arcade.software/insights
```

**Response (200)**

```json
[
  {
    "id": "company_abc123",
    "name": "Acme Corporation",
    "domain": "acme.com",
    "logo": "https://logo.clearbit.com/acme.com",
    "industry": "Technology",
    "employeeRange": "501-1000",
    "city": "San Francisco",
    "state": "California",
    "country": "United States",
    "estimatedAnnualRevenue": "$50M-$100M",
    "linkedin": "https://linkedin.com/company/acme",
    "twitter": "https://twitter.com/acme",
    "facebook": "https://facebook.com/acme",
    "crunchbase": "https://crunchbase.com/organization/acme",
    "ips": ["192.168.1.1", "192.168.1.2"],
    "role": "Engineering",
    "seniority": "Manager",
    "last30d": 45,
    "last7d": 12,
    "yesterday": 3,
    "normalizedScore30d": 0.92,
    "normalizedScore7d": 0.78,
    "normalizedScoreYesterday": 0.65,
    "byDate": {
      "2025-01-19": { "plays": 3, "players": 2, "flowCount": 2 },
      "2025-01-18": { "plays": 5, "players": 3, "flowCount": 3 }
    },
    "flows": [
      { "flowId": "flow_abc123", "flowName": "Product Onboarding", "playCount": 8 },
      { "flowId": "flow_def456", "flowName": "Feature Walkthrough", "playCount": 4 }
    ]
  },
  {
    "id": "company_def456",
    "name": "TechCorp Inc",
    "domain": "techcorp.io",
    "logo": "https://logo.clearbit.com/techcorp.io",
    "industry": "Software",
    "employeeRange": "51-200",
    "city": "Austin",
    "state": "Texas",
    "country": "United States",
    "estimatedAnnualRevenue": "$10M-$50M",
    "linkedin": "https://linkedin.com/company/techcorp",
    "twitter": null,
    "facebook": null,
    "crunchbase": null,
    "ips": ["10.0.0.1"],
    "role": "Product",
    "seniority": "Director",
    "last30d": 28,
    "last7d": 8,
    "yesterday": 2,
    "normalizedScore30d": 0.75,
    "normalizedScore7d": 0.62,
    "normalizedScoreYesterday": 0.45,
    "byDate": {
      "2025-01-19": { "plays": 2, "players": 1, "flowCount": 1 },
      "2025-01-18": { "plays": 3, "players": 2, "flowCount": 2 }
    },
    "flows": [
      { "flowId": "flow_abc123", "flowName": "Product Onboarding", "playCount": 5 }
    ]
  }
]
```

***

#### Team Played Flows for IPs

Returns flows played by viewers from specific IP addresses.

**Type:** `teamPlayedFlowsForIps`

**Request Body**

```json
{
  "type": "teamPlayedFlowsForIps",
  "teamId": "TEAM_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z",
  "ips": ["192.168.1.1", "10.0.0.1"]
}
```

**Example**

```bash
curl -sS \
  -X POST \
  -H "Authorization: YOUR_ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "teamPlayedFlowsForIps",
    "teamId": "TEAM_ID",
    "from": "2025-01-01T00:00:00.000Z",
    "to": "2025-01-20T23:59:59.000Z",
    "ips": ["192.168.1.1"]
  }' \
  https://api.arcade.software/insights
```

**Response (200)**

```json
[
  {
    "flowId": "flow_abc123",
    "name": "Product Onboarding"
  },
  {
    "flowId": "flow_def456",
    "name": "Feature Walkthrough"
  }
]
```

***

### Response Field Reference

#### Play Metrics

| Field              | Description                                        |
| ------------------ | -------------------------------------------------- |
| `players`          | Number of unique viewers                           |
| `plays`            | Number of unique play sessions                     |
| `completers`       | Number of unique viewers who completed the flow    |
| `completions`      | Number of unique sessions that completed           |
| `anyCtaClickers`   | Number of unique viewers who clicked any CTA       |
| `anyCtaClicks`     | Total clicks on any CTA                            |
| `finalCtaClickers` | Number of unique viewers who clicked the final CTA |
| `finalCtaClicks`   | Total clicks on the final CTA                      |

#### Company Fields

| Field                    | Description                           |
| ------------------------ | ------------------------------------- |
| `id`                     | Unique company identifier             |
| `name`                   | Company name                          |
| `domain`                 | Company domain                        |
| `logo`                   | URL to company logo                   |
| `industry`               | Company industry                      |
| `employeeRange`          | Employee count range (e.g., "51-200") |
| `estimatedAnnualRevenue` | Revenue range (e.g., "$10M-$50M")     |
| `playCount`              | Total plays from this company         |
| `normalizedScore`        | Engagement score (0-1)                |

***

### Filtering

#### By Folders and Tags

Team-level endpoints (`totalPlays`, `overviewPlays`, `playTimeByTeam`) support filtering:

```json
{
  "type": "totalPlays",
  "teamId": "TEAM_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z",
  "folderIds": ["folder_abc123", "folder_def456"],
  "tagIds": ["tag_xyz789"]
}
```

#### By IP Addresses

Flow-level endpoints support filtering by IP:

```json
{
  "type": "plays",
  "teamId": "TEAM_ID",
  "flowId": "FLOW_ID",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-20T23:59:59.000Z",
  "ips": ["192.168.1.1", "10.0.0.1"]
}
```

***

### Pagination

Endpoints that support pagination (`overviewPlays`):

| Parameter | Default | Min | Max |
| --------- | ------- | --- | --- |
| `page`    | 1       | 1   | -   |
| `size`    | 20      | 1   | 100 |

***

### Date Formats

All dates must be in ISO 8601 format with timezone:

```
2025-01-01T00:00:00.000Z
2025-01-20T23:59:59.999Z
```

The `from` date is required. The `to` date defaults to the current UTC time if not provided.

```
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.arcade.software/kb/leverage/advanced-features/rest-api/insights-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.