# 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 **Growth or above**.

#### 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.

```
```