Arcade Insights API (Public)
This document describes Arcade's insights endpoints for customers who want to access flow analytics data programmatically.
https://api.arcade.software/insights
makefile Copy code
How do I authenticate with the API?
All requests must include your Arcade API key in the Authorization header.
Generate an API key
Go to Settings > Advanced in your Workspace settings.
Select Generate a new API key.
In the modal:
The Insights API key does not require provisioning scope.
Requirements & Limits
Plan requirement: the API key must belong to a workspace on Growth or above.
100 requests per minute per IP
Error Responses (Common)
All responses are JSON.
401 Unauthorized
403 Forbidden
400 Bad Request
5xx Server Errors
All insights endpoints use POST method with a JSON body. The type field specifies which insight to retrieve.
Common Parameters
Parameter
Type
Required
Description
The insight type (e.g., plays, views)
Flow ID (required for flow-level insights)
Start date (e.g., 2025-01-01T00:00:00.000Z)
End date (e.g., 2025-01-20T23:59:59.000Z)
Exclude internal viewers from results
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:
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:
Returns plays, completions, and CTA clicks for a flow.
Type: plays
Request Body
Example
Response (200)
Response with compareToPrevious: true
Returns unique viewers for a flow.
Type: views
Request Body
Example
Response (200)
Response with compareToPrevious: true
Returns step dropoff analysis for a flow.
Type: dropoff
Request Body
Example
Response (200)
Returns average play time for a flow.
Type: playTime
Request Body
Example
Response (200)
Response with compareToPrevious: true
Returns companies that viewed a flow (via IP-based identification).
Type: companies
Request Body
Example
Response (200)
Custom Link Insights
Views by Custom Link
Returns unique views grouped by custom link ID.
Type: viewsByCustomLinkId
Request Body
Example
Response (200)
Plays by Custom Link
Returns plays grouped by custom link ID.
Type: playsByCustomLinkId
Request Body
Example
Response (200)
Play Time by Custom Link
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)
Returns total plays, completions, and CTA clicks for an entire team.
Type: totalPlays
Plan Required: Pro
Request Body
Example
Response (200)
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
Number of unique play sessions
Number of unique viewers who completed the flow
Number of unique sessions that completed
Number of unique viewers who clicked any CTA
Number of unique viewers who clicked the final CTA
Total clicks on the final CTA
Unique company identifier
Employee count range (e.g., "51-200")
Revenue range (e.g., "$10M-$50M")
Total plays from this company
Team-level endpoints (totalPlays, overviewPlays, playTimeByTeam) support filtering:
By IP Addresses
Flow-level endpoints support filtering by IP:
Endpoints that support pagination (overviewPlays):
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.