Get form
GET /forms/{form}/response-summary. Parameters, permissions, request and response schemas.
GET /forms/{form}/response-summary
Get form. Requires the REST read token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.
Authentication
Use a team API key as Authorization: Bearer YOUR_API_KEY. The token ability and the user’s role must both allow this operation. See authentication.
{
"ability": "read",
"team": "Token-bound Team",
"authorization": "Additional role, entity-policy and plan requirements vary by operation."
}Parameters
| Name | Location | Required | Description |
|---|---|---|---|
form | path | Yes | The form ID |
sample_limit | query | No | Sample Limit. |
theme_limit | query | No | Theme Limit. |
form
{
"type": "integer",
"minimum": 1
}sample_limit
{
"type": "integer",
"minimum": 1,
"maximum": 20
}theme_limit
{
"type": "integer",
"minimum": 0,
"maximum": 10
}Example request
curl --request GET 'https://api.example.test/api/forms/1/response-summary' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Accept: application/json'Examples use fictional data. Replace resource IDs and the API host with your environment’s values.
Responses
200
Successful response.
Content type: application/json.
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"form_id": {
"type": "integer"
},
"generated_at": {
"type": "string"
},
"totals": {
"type": "object",
"properties": {
"responses": {
"type": "integer",
"minimum": 0
},
"submitted": {
"type": "integer",
"minimum": 0
},
"partial": {
"type": "integer",
"minimum": 0
},
"questions": {
"type": "integer",
"minimum": 0
},
"answers": {
"type": "integer",
"minimum": 0
},
"completion_rate": {
"type": "number"
},
"answer_rate": {
"type": "number"
}
},
"required": [
"responses",
"submitted",
"partial",
"questions",
"answers",
"completion_rate",
"answer_rate"
]
},
"questions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
},
"step_title": {
"type": [
"string",
"null"
]
},
"responses": {
"type": "object",
"properties": {
"answered": {
"type": "integer",
"minimum": 0
},
"skipped": {
"type": "integer",
"minimum": 0
},
"response_rate": {
"type": "number"
}
},
"required": [
"answered",
"skipped",
"response_rate"
]
},
"distribution": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"label": {
"type": "string"
},
"count": {
"type": "integer"
},
"percentage": {
"type": "number"
}
},
"required": [
"value",
"label",
"count",
"percentage"
]
}
},
"metrics": {
"anyOf": [
{
"type": "object",
"properties": {
"average": {
"type": "number"
},
"min": {
"type": "number"
},
"max": {
"type": "number"
},
"nps": {
"type": "object",
"properties": {
"score": {
"type": "integer"
},
"promoters": {
"type": "integer",
"minimum": 0
},
"passives": {
"type": "integer",
"minimum": 0
},
"detractors": {
"type": "integer",
"minimum": 0
}
},
"required": [
"score",
"promoters",
"passives",
"detractors"
]
}
},
"required": [
"average",
"min",
"max"
]
},
{
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 0
},
{
"type": "object",
"properties": {
"emoji": {
"type": "object",
"properties": {
"average_score": {
"type": "number"
},
"max_score": {
"type": "integer"
},
"positive": {
"type": "integer",
"minimum": 0
},
"neutral": {
"type": "integer"
},
"negative": {
"type": "integer",
"minimum": 0
},
"scale": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"label": {
"type": "string"
},
"score": {
"type": "integer"
},
"count": {
"type": "integer"
},
"percentage": {
"type": "number"
}
},
"required": [
"value",
"label",
"score",
"count",
"percentage"
]
}
},
"top_reaction": {
"type": [
"object",
"null"
],
"properties": {
"value": {
"type": "string"
},
"label": {
"type": "string"
},
"score": {
"type": "integer"
},
"count": {
"type": "integer"
},
"percentage": {
"type": "number"
}
},
"required": [
"value",
"label",
"score",
"count",
"percentage"
]
}
},
"required": [
"average_score",
"max_score",
"positive",
"neutral",
"negative",
"scale",
"top_reaction"
]
}
},
"required": [
"emoji"
]
}
]
},
"theme_candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "integer"
},
"examples": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"label",
"count",
"examples"
]
}
},
"samples": {
"type": "array",
"items": {
"type": "object",
"properties": {
"answer_id": {
"type": "integer"
},
"response_id": {
"type": "integer"
},
"status": {
"type": "string"
},
"value": {
"type": "string"
},
"raw_value": {
"type": [
"string",
"null"
]
},
"page_url": {
"type": [
"string",
"null"
]
},
"submitted_at": {
"type": [
"string",
"null"
]
},
"updated_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"answer_id",
"response_id",
"status",
"value",
"raw_value",
"page_url",
"submitted_at",
"updated_at"
]
}
}
},
"required": [
"id",
"title",
"description",
"type",
"step_title",
"responses",
"distribution",
"metrics",
"theme_candidates",
"samples"
]
}
}
},
"required": [
"form_id",
"generated_at",
"totals",
"questions"
]
}
},
"required": [
"data"
]
}{
"data": {
"form_id": 101,
"generated_at": "example",
"totals": {
"responses": 1,
"submitted": 1,
"partial": 1,
"questions": 1,
"answers": 1,
"completion_rate": 1,
"answer_rate": 1
},
"questions": [
{
"id": 101,
"title": "Checkout delivery estimate",
"description": null,
"type": "example",
"step_title": null,
"responses": {
"answered": 1,
"skipped": 1,
"response_rate": 1
},
"distribution": [
{
"value": "example",
"label": "example",
"count": 1,
"percentage": 1
}
],
"metrics": {
"average": 1,
"min": 1,
"max": 1
},
"theme_candidates": [
{
"label": "example",
"count": 1,
"examples": []
}
],
"samples": [
{
"answer_id": 101,
"response_id": 101,
"status": "example",
"value": "example",
"raw_value": null,
"page_url": null,
"submitted_at": null,
"updated_at": null
}
]
}
]
}
}401
Unauthenticated
Content type: application/json.
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}{
"message": "The request could not be completed."
}403
Authorization error
Content type: application/json.
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}{
"message": "The request could not be completed."
}404
Not found
Content type: application/json.
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}{
"message": "The request could not be completed."
}422
Validation error
Content type: application/json.
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Errors overview."
},
"errors": {
"type": "object",
"description": "A detailed description of each field that failed validation.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"required": [
"message",
"errors"
]
}{
"message": "The request could not be completed.",
"errors": {
"name": [
"The name field is required."
]
}
}429
Rate limit exceeded. Honor Retry-After before retrying.
Response headers:
{
"Retry-After": {
"description": "Seconds before retrying.",
"schema": {
"type": "integer"
}
}
}Content type: application/json.
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Too Many Attempts."
}
},
"required": [
"message"
]
}{
"message": "Too Many Attempts."
}See API conventions for error handling, rate limits, pagination, and uploads.