Skip to main content
GET
/
api
/
v1
/
forms
/
{formId}
/
analytics
Get Form Analytics
curl --request GET \
  --url https://api.example.com/api/v1/forms/{formId}/analytics
{
  "totalSubmissions": 123,
  "dailySubmissionRate": 123,
  "last24HoursSubmissions": 123,
  "timeSeriesData": [
    {
      "time": "<string>",
      "submissions": 123
    }
  ],
  "timeRange": "<string>",
  "plan": "<string>",
  "weekOverWeekGrowth": 123,
  "peakSubmissionHour": 123,
  "browserStats": [
    {
      "name": "<string>",
      "count": 123,
      "percentage": 123
    }
  ],
  "locationStats": [
    {
      "name": "<string>",
      "count": 123,
      "percentage": 123
    }
  ],
  "error": "<string>"
}

​
Overview

This endpoint provides comprehensive analytics data for a form. The response includes basic metrics for STANDARD plan users and extended analytics including browser statistics and location data for PRO plan users.
Analytics are only available with the STANDARD or PRO plan. FREE plan users will receive a 403 error.

​
Authentication

This endpoint requires a valid API key. The API key can be provided in two ways:
  1. Header (Recommended): X-API-Key: your_api_key
  2. Query Parameter: ?apiKey=your_api_key

​
Path Parameters

​
formId
string
required
The unique identifier of the form to retrieve analytics for.

​
Query Parameters

​
apiKey
string
API key for authentication. Only required if not provided in the X-API-Key header.
​
timeRange
string
default:"week"
Time range for the time series data.

​
Response

​
totalSubmissions
number
Total number of submissions received for this form.
​
dailySubmissionRate
number
Average number of submissions per day since the form was created. Rounded to 2 decimal places.
​
last24HoursSubmissions
number
Number of submissions received in the last 24 hours.
​
timeSeriesData
array
Array of time series data points showing submission counts over the specified time range.
​
timeRange
string
The time range used for the analytics data (echoes the query parameter).
​
plan
string
The user’s current plan: STANDARD or PRO.

​
PRO Plan Only Fields

The following fields are only included for PRO plan users:
​
weekOverWeekGrowth
number
Week-over-week growth rate calculated as the percentage change between the last 7 days and the previous 7 days. Rounded to 2 decimal places.
​
peakSubmissionHour
number
Hour of the day (0-23) when submissions are most frequently received.
​
browserStats
array
Statistics on which browsers were used to submit the form.
​
locationStats
array
Statistics on submission locations by country.

​
Rate Limiting

This endpoint is rate-limited. When rate limits are exceeded, you’ll receive a 429 status code with the following headers:
  • X-RateLimit-Limit: Maximum number of requests allowed
  • X-RateLimit-Remaining: Number of requests remaining
  • X-RateLimit-Reset: Unix timestamp when the rate limit resets

​
Examples

curl -X GET "https://api.mantlz.com/api/v1/forms/form_123/analytics?timeRange=week" \
  -H "X-API-Key: your_api_key"

​
Response Example (STANDARD Plan)

{
  "totalSubmissions": 247,
  "dailySubmissionRate": 12.35,
  "last24HoursSubmissions": 18,
  "timeSeriesData": [
    { "time": "Mon", "submissions": 32 },
    { "time": "Tue", "submissions": 28 },
    { "time": "Wed", "submissions": 35 },
    { "time": "Thu", "submissions": 41 },
    { "time": "Fri", "submissions": 38 },
    { "time": "Sat", "submissions": 15 },
    { "time": "Sun", "submissions": 18 }
  ],
  "timeRange": "week",
  "plan": "STANDARD"
}

​
Response Example (PRO Plan)

{
  "totalSubmissions": 247,
  "dailySubmissionRate": 12.35,
  "last24HoursSubmissions": 18,
  "timeSeriesData": [
    { "time": "Mon", "submissions": 32 },
    { "time": "Tue", "submissions": 28 },
    { "time": "Wed", "submissions": 35 },
    { "time": "Thu", "submissions": 41 },
    { "time": "Fri", "submissions": 38 },
    { "time": "Sat", "submissions": 15 },
    { "time": "Sun", "submissions": 18 }
  ],
  "timeRange": "week",
  "plan": "PRO",
  "weekOverWeekGrowth": 0.15,
  "peakSubmissionHour": 14,
  "browserStats": [
    { "name": "Chrome", "count": 142, "percentage": 0.575 },
    { "name": "Firefox", "count": 58, "percentage": 0.235 },
    { "name": "Safari", "count": 35, "percentage": 0.142 },
    { "name": "Edge", "count": 12, "percentage": 0.048 }
  ],
  "locationStats": [
    { "name": "United States", "count": 128, "percentage": 0.518 },
    { "name": "United Kingdom", "count": 45, "percentage": 0.182 },
    { "name": "Canada", "count": 32, "percentage": 0.130 },
    { "name": "Germany", "count": 28, "percentage": 0.113 },
    { "name": "Australia", "count": 14, "percentage": 0.057 }
  ]
}

​
Error Responses

​
error
string
Error message describing what went wrong.

​
Common Errors

Status CodeError MessageDescription
400Invalid timeRange parametertimeRange must be “day”, “week”, or “month”
401Invalid or inactive API keyThe provided API key is invalid or has been revoked
403Analytics are only available with the STANDARD or PRO planUser is on the FREE plan which doesn’t include analytics
404Form not foundThe form doesn’t exist or doesn’t belong to the user
429Rate limit exceededToo many requests, wait for rate limit to reset
500Internal server errorServer encountered an error processing the request

Build docs developers (and LLMs) love

Get started for freeTalk to us