Clipform Analytics API
Read funnel analytics, submissions, and results for a form.
Read funnel analytics, submissions, and results for a form.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/clipform-io:clipform-io-analytics-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Clipform Io Analytics API
version: 1.0.0
contact:
name: Clipform
url: https://clipform.io
email: support@clipform.io
termsOfService: https://clipform.io/terms
description: 'Operations tagged Analytics across 2 of this provider''s published API definitions: api.clipform.io_openapi.json, clipform-io-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.clipform.io/v1
description: Production
x-internal: false
tags:
- name: Analytics
x-displayName: Analytics
description: Read funnel analytics, submissions, and results for a form.
paths:
/forms/{formId}/analytics:
get:
operationId: getFormAnalytics
tags:
- Analytics
summary: Get form analytics
description: Returns funnel analytics for a form.
parameters:
- name: formId
in: path
required: true
schema:
type: string
format: uuid
maxLength: 36
- name: start_date
in: query
schema:
type: string
format: date-time
maxLength: 30
description: Filter from this date (ISO 8601)
- name: end_date
in: query
schema:
type: string
format: date-time
maxLength: 30
description: Filter until this date (ISO 8601)
- name: referrer_url
in: query
schema:
type: string
maxLength: 2000
description: Filter by referrer. Matches by normalized host and path (scheme, port, query, fragment and a leading www. are ignored); `(direct)` matches sessions with no referrer. Referrer breakdown rows in the response return that same normalized key as their name.
- name: country_code
in: query
schema:
type: string
maxLength: 2000
description: Filter by ISO 3166-1 alpha-2 country code, in any case (`gb` and `GB` are equivalent). `unknown` matches sessions with no country.
- name: browser
in: query
schema:
type: string
maxLength: 2000
description: Filter by browser name
- name: device_type
in: query
schema:
type: string
maxLength: 2000
description: Filter by device type (desktop, mobile, tablet)
security:
- bearerAuth: []
responses:
'200':
description: Analytics data
content:
application/json:
schema:
type: object
properties:
total_views:
type: integer
format: int32
minimum: 0
maximum: 2147483647
total_started:
type: integer
format: int32
minimum: 0
maximum: 2147483647
total_completed:
type: integer
format: int32
minimum: 0
maximum: 2147483647
total_unique_visitors:
type: integer
format: int32
minimum: 0
maximum: 2147483647
views_series:
type: array
items:
type: object
properties:
date:
type: string
maxLength: 2000
value:
type: integer
format: int32
minimum: 0
maximum: 2147483647
maxItems: 500
started_series:
type: array
items:
type: object
maxItems: 500
completed_series:
type: array
items:
type: object
maxItems: 500
'429':
$ref: '#/components/responses/RateLimited'
servers:
- url: https://api.clipform.io/v1
description: Production
x-internal: false
/forms/{formId}/submissions:
get:
operationId: getFormSubmissions
tags:
- Analytics
summary: List submissions
description: Returns a form's submissions.
parameters:
- name: formId
in: path
required: true
schema:
type: string
format: uuid
maxLength: 36
- name: submission_id
in: query
schema:
type: string
format: uuid
maxLength: 36
description: Filter to the response_set with this id (may still return more than one row if it has multiple completed sessions).
security:
- bearerAuth: []
responses:
'200':
description: List of submissions
content:
application/json:
schema:
type: array
items:
type: object
properties:
submission_id:
type: string
format: uuid
maxLength: 36
description: 'Stable per-row key: one row per completed session (id = that session''s id), or one row for a still-open response_set with no completed session yet (id = the response_set''s id).
'
response_set_id:
type: string
format: uuid
maxLength: 36
description: The parent response_set - may repeat across sibling completions of the same set.
session_id:
type: string
format: uuid
nullable: true
maxLength: 36
status:
type: string
maxLength: 2000
processing_status:
type: string
nullable: true
maxLength: 2000
description: 'Back-office processing lifecycle: none/complete (ready), pending/processing (in-flight - answers not yet final), processing_error/failed (released unverified).
'
created_at:
type: string
format: date-time
maxLength: 30
completed_at:
type: string
format: date-time
nullable: true
maxLength: 30
last_activity_at:
type: string
format: date-time
maxLength: 30
description: When the respondent last made progress (falls back to created_at)
total_sessions:
type: integer
format: int32
minimum: 0
maximum: 2147483647
total_responses:
type: integer
format: int32
minimum: 0
maximum: 2147483647
contact_email:
type: string
nullable: true
maxLength: 2000
contact_first_name:
type: string
nullable: true
maxLength: 2000
contact_last_name:
type: string
nullable: true
maxLength: 2000
node_responses:
type: object
nullable: true
locked:
type: boolean
description: 'True when this response is over the workspace''s plan limit. Locked rows have their answer/contact fields nulled.
'
maxItems: 500
'429':
$ref: '#/components/responses/RateLimited'
servers:
- url: https://api.clipform.io/v1
description: Production
x-internal: false
/forms/{formId}/submissions/{submissionId}:
get:
operationId: getSubmissionDetails
tags:
- Analytics
summary: Get a submission
description: Returns one submission in full.
parameters:
- name: formId
in: path
required: true
schema:
type: string
format: uuid
maxLength: 36
- name: submissionId
in: path
required: true
schema:
type: string
format: uuid
maxLength: 36
description: The submission's response_set_id
- name: session_id
in: query
schema:
type: string
format: uuid
maxLength: 36
description: Scope the detail to one completed session of this response_set (from list submissions' session_id). Omit for the set-level (in-progress) view.
security:
- bearerAuth: []
responses:
'200':
description: Submission details
content:
application/json:
schema:
type: object
'403':
description: 'The response is over the workspace''s plan limit and locked. Upgrade to view it.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Submission not found for this form
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/RateLimited'
servers:
- url: https://api.clipform.io/v1
description: Production
x-internal: false
/forms/{formId}/results:
get:
operationId: getFormResults
tags:
- Analytics
summary: Get form results
description: Returns aggregated results for a form.
parameters:
- name: formId
in: path
required: true
schema:
type: string
format: uuid
maxLength: 36
security:
- bearerAuth: []
responses:
'200':
description: Aggregated results
content:
application/json:
schema:
type: object
properties:
total_responses:
type: integer
format: int32
minimum: 0
maximum: 2147483647
public_results_allowed:
type: boolean
description: Whether this workspace may enable the public results portal, server-computed from the rollout flag and allowlist.
results_url:
type: string
format: uri
description: Dashboard Responses tab for this form. Absent for an anonymous caller.
maxLength: 2048
nodes:
type: array
items:
type: object
properties:
node_id:
type: string
maxLength: 64
node_text:
type: string
maxLength: 2000
node_type:
type: string
maxLength: 2000
total_responses:
type: integer
format: int32
minimum: 0
maximum: 2147483647
total_views:
type: integer
format: int32
minimum: 0
maximum: 2147483647
in_live_form:
type: boolean
description: Whether respondents can reach this question now, judged on the published version for a live form and on the builder draft otherwise.
selection_mode:
type: string
enum:
- single
- multiple
nullable: true
description: Choice nodes only. `multiple` means a respondent can pick several options, so the per-option counts can add up past total_responses.
answers:
type: array
items:
type: object
maxItems: 500
maxItems: 500
flow:
type: object
properties:
nodes:
type: array
items:
type: object
maxItems: 500
links:
type: array
items:
type: object
maxItems: 500
'429':
$ref: '#/components/responses/RateLimited'
servers:
- url: https://api.clipform.io/v1
description: Production
x-internal: false
/results/public/{resultsShareId}:
get:
operationId: getPublicResults
tags:
- Analytics
summary: Get public results
description: Returns a form's aggregated results for anyone holding its public results link.
security: []
parameters:
- name: resultsShareId
in: path
required: true
schema:
type: string
description: 24-character lowercase hex public results token.
maxLength: 2000
responses:
'200':
description: Aggregated results, contact/file/payment nodes and locked responses excluded
content:
application/json:
schema:
type: object
properties:
total_responses:
type: integer
format: int32
minimum: 0
maximum: 2147483647
nodes:
type: array
items:
type: object
properties:
node_id:
type: string
maxLength: 64
node_text:
type: string
maxLength: 2000
node_type:
type: string
maxLength: 2000
total_responses:
type: integer
format: int32
minimum: 0
maximum: 2147483647
total_views:
type: integer
format: int32
minimum: 0
maximum: 2147483647
selection_mode:
type: string
enum:
- single
- multiple
nullable: true
description: Choice nodes only. `multiple` means a respondent can pick several options, so the per-option counts can add up past total_responses.
answers:
type: array
items:
type: object
maxItems: 500
maxItems: 500
flow:
type: object
'404':
description: Results not found (unknown or rotated token, or the owner has not enabled public results)
'429':
$ref: '#/components/responses/RateLimited'
servers:
- url: https://api.clipform.io/v1
description: Production
x-internal: false
components:
schemas:
Error:
type: object
description: Standard error envelope returned by every failed request.
required:
- code
- error
properties:
code:
type: string
description: Machine-readable error code. Keep in lockstep with the ErrorCode union in apps/api/src/lib/errors.ts (source of truth).
enum:
- VALIDATION_ERROR
- UNKNOWN_SESSION
- RATE_LIMITED
- UNAUTHORIZED
- FORBIDDEN
- NOT_FOUND
- INTERNAL_ERROR
- RENDER_FAILED
- PAYMENT_ERROR
- BOOKING_ERROR
- PLAN_LIMIT
- RESPONSE_LIMIT
- CONFLICT
error:
type: string
description: Human-readable error message.
maxLength: 2000
details:
description: 'Optional structured detail; present on some validation errors. The fallback 401 ("Authentication required...") carries `details.reason` for a rejected Bearer session token: `no_token`, `token_rejected`, `auth_unavailable`, `not_a_member`, `no_workspace`, `membership_lookup_failed`, or `not_evaluated`, plus `auth_code` and `auth_status` when the auth provider returned them.'
responses:
RateLimited:
description: Rate limit exceeded.
headers:
Access-Control-Allow-Origin:
description: CORS origin permitted to read the response.
schema:
type: string
maxLength: 2048
example: '*'
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
format: int32
minimum: 0
maximum: 86400
example: 42
RateLimit-Limit:
description: Request quota for the current window.
schema:
type: integer
format: int32
minimum: 0
maximum: 1000000
example: 60
RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
format: int32
minimum: 0
maximum: 1000000
example: 0
RateLimit-Reset:
description: Seconds until the current window resets.
schema:
type: integer
format: int32
minimum: 0
maximum: 86400
example: 42
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key (cf_*) passed as Bearer token
oauth2:
type: oauth2
description: Authorization-code OAuth for installed apps acting on a user's workspace. Access tokens (cf_at_*) are passed as Bearer tokens and authorize the Integrations operations. They are opaque, single-audience, server-side records. Client credentials are issued per app - contact support@clipform.io.
flows:
authorizationCode:
authorizationUrl: https://api.clipform.io/oauth/authorize
tokenUrl: https://api.clipform.io/oauth/token
refreshUrl: https://api.clipform.io/oauth/token
scopes:
forms:read: Read the workspace's forms.
responses:read: Read the workspace's form responses.
webhooks:manage: Subscribe and unsubscribe webhook endpoints.
x-refined-from:
- api.clipform.io_openapi.json
- clipform-io-openapi.yml