List summary
Sums up a form's responses: how many were begun and completed, and for each field how many answered it, the distribution of what was said (choices, points, yes and no), the mean, least and most of a number, and how many open responses stopped in front of it.
GET /v1/form/forms/{id}/summary
| Address | https://api.hanzo.ai/v1/form/forms/{id}/summary |
| Method | GET |
| Operation | summarize_form |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Sums up a form's responses: how many were begun and completed, and for each field how many answered it, the distribution of what was said (choices, points, yes and no), the mean, least and most of a number, and how many open responses stopped in front of it. since and until narrow it to when the responses were made. At most the newest 50000 are read, and truncated says so. An org admin only.
Request
3 fields.
| Field | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the form's id or slug, from the path. |
since | query | string | — | Since keeps the responses made at or after it, RFC 3339. |
until | query | string | — | Until keeps the responses made before it, RFC 3339. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | form.Summary | ok |
default | problem-details | refused |
200 body — 20 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
completion_rate | body | number (double) | — | CompletionRate is completions over starts, 0 to 1. |
completions | body | integer (int64) | — | Completions is how many were completed. |
fields | body | form.FieldSummary[] | — | Fields are each asked field's figures, in form order. |
fields[].answered | body | integer (int64) | — | Answered is how many responses answer it. |
fields[].distribution | body | form.Tally[] | — | Distribution counts each value: every choice of a multiple_choice or dropdown (with its label), every point of a rating or opinion_scale, and yes and no. |
fields[].distribution[].count | body | integer (int64) | — | |
fields[].distribution[].label | body | string | — | |
fields[].distribution[].value | body | string | — | |
fields[].drop_off | body | integer (int64) | — | DropOff is how many open responses stopped in front of it: this is the first field they left unanswered after the last one they answered. |
fields[].field | body | string | — | Field is the field's ref; Type its type; Title its question. |
fields[].max | body | number (double) | — | |
fields[].mean | body | number (double) | — | Mean, Min and Max are a number, rating or opinion_scale's. |
fields[].min | body | number (double) | — | |
fields[].title | body | string | — | |
fields[].type | body | string | — | |
form | body | string | — | Form is the form's id. |
scanned | body | integer (int64) | — | Scanned is how many responses were read; Truncated says the form has more than one summary reads (50000), and the newest were read. |
starts | body | integer (int64) | — | Starts is how many responses were begun: open and completed. |
truncated | body | boolean | — | |
views | body | integer (int64) | — | Views is null: a view is stated on the event stream as form_viewed and counted there, not kept with the responses. |
Failure carries the platform error shape — see Errors.
Examples
hanzo form forms summary <id>import { Configuration, FormApi } from 'hanzoai';
const api = new FormApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.summarizeForm({ id: 'id' });from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import FormApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = FormApi(client).summarize_form(id='id')cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)
resp, _, err := client.FormAPI.SummarizeForm(context.Background()).Execute()
if err != nil {
return err
}use hanzo_client::apis::{configuration::Configuration, form_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = form_api::summarize_form(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.FormApi;
ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));
var result = new FormApi(client).summarizeForm();The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →
curl https://api.hanzo.ai/v1/form/forms/<id>/summary \
-H "Authorization: Bearer $HANZO_API_KEY"Tool form, op summarize_form — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.
curl -X POST https://api.hanzo.ai/v1/mcp \
-H "Authorization: Bearer $HANZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "form",
"arguments": {
"op": "summarize_form",
"input": {
"id": "<id>"
}
}
}
}'