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

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

403 Forbidden

400 Bad Request

5xx Server Errors


Request Format

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

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


Flow Insights

Plays

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

Type: plays

Request Body

Example

Response (200)

Response with compareToPrevious: true


Views

Returns unique viewers for a flow.

Type: views

Request Body

Example

Response (200)

Response with compareToPrevious: true


Dropoff

Returns step dropoff analysis for a flow.

Type: dropoff

Request Body

Example

Response (200)


Play Time

Returns average play time for a flow.

Type: playTime

Request Body

Example

Response (200)

Response with compareToPrevious: true


Companies

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

Type: companies

Request Body

Example

Response (200)


Returns unique views grouped by custom link ID.

Type: viewsByCustomLinkId

Request Body

Example

Response (200)


Returns plays grouped by custom link ID.

Type: playsByCustomLinkId

Request Body

Example

Response (200)


Returns average play time grouped by custom link ID.

Type: playTimeByCustomLinkId

Request Body

Example

Response (200)


Authenticated Views

Returns authenticated viewer details for a flow.

Type: authenticatedViews

Request Body

Example

Response (200)


Team Insights

Total Plays

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

Type: totalPlays

Plan Required: Pro

Request Body

Example

Response (200)


Overview Plays

Returns plays per flow for a team.

Type: overviewPlays

Plan Required: Pro

Request Body

Example

Response (200)


Play Time by Team

Returns average play time for an entire team.

Type: playTimeByTeam

Plan Required: Pro

Request Body

Example

Response (200)


Companies for Leads

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

Type: companiesForLeads

Plan Required: Pro

Request Body

Example

Response (200)


Team Played Flows for IPs

Returns flows played by viewers from specific IP addresses.

Type: teamPlayedFlowsForIps

Request Body

Example

Response (200)


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:

By IP Addresses

Flow-level endpoints support filtering by IP:


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:

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

Last updated

Was this helpful?