Get Form Analytics

Retrieve detailed analytics for a specific form including submission metrics, time series data, and advanced insights.

GET /api/v1/forms/{formId}/analytics

Get Form Analytics

cURL

curl --request GET \
  --url https://api.example.com/api/v1/forms/{formId}/analytics

200

{
  "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.

Show Available values

• day - Hourly data for the last 24 hours
• week - Daily data for the last 7 days
• month - Daily data for the last 30 days

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.

Show properties

time · string

Time label for the data point. Format depends on timeRange:

• day: “0:00”, “1:00”, etc. (24 hour format)
• week: “Mon”, “Tue”, etc. (day names)
• month: “3/1”, “3/2”, etc. (month/day format)

submissions · number

Number of submissions during this time period.

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.

Show properties

name · string

Browser name (e.g., “Chrome”, “Firefox”, “Safari”, “Edge”).

count · number

Number of submissions from this browser.

percentage · number

Percentage of total submissions from this browser (0-1 range).

locationStats · array

Statistics on submission locations by country.

Show properties

name · string

Country name (e.g., “United States”, “United Kingdom”).

count · number

Number of submissions from this country.

percentage · number

Percentage of total submissions from this country (0-1 range).

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

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 Code	Error Message	Description
400	Invalid timeRange parameter	timeRange must be “day”, “week”, or “month”
401	Invalid or inactive API key	The provided API key is invalid or has been revoked
403	Analytics are only available with the STANDARD or PRO plan	User is on the FREE plan which doesn’t include analytics
404	Form not found	The form doesn’t exist or doesn’t belong to the user
429	Rate limit exceeded	Too many requests, wait for rate limit to reset
500	Internal server error	Server encountered an error processing the request