---
name: "forms_summary"
area: "forms"
title: "Summarize responses"
price: "free"
method: "POST"
url: "https://api.conecto.chat/v1/tools/forms_summary"
mcp_server: "https://api.conecto.chat/mcp/forms"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/forms/forms_summary"
---

# Summarize responses (`forms_summary`)

A form's results at a glance: choice counts, rating averages, the NPS score, yes and no shares, numbers and the latest text answers.

A form's results at a glance: the response count and, per question, choice counts and percentages, rating averages and distributions, the NPS score (percent promoters minus percent detractors), yes and no shares, number minimum, maximum and average, and the 5 latest text answers. With since, only responses from then on.

Price: Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads. A call that fails costs nothing.

## Use it when

Someone asks how a survey turned out, or for the NPS.

## Say this to your agent

> How did customers rate their repairs this month, and what's our NPS?

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `form` | string | yes | The form's form_id or slug (forms_list shows both). 1 to 60 characters. |  |  |
| `since` | string | no | Only responses from this time on: ISO 8601 (2026-10-01T00:00:00Z) or a date (2026-10-01, UTC). Up to 40 characters. |  |  |

## Example

Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon.

MCP: call `forms_summary` on the MCP server `https://api.conecto.chat/mcp/forms` with these arguments:

```json
{
  "form": "repair-feedback",
  "since": "2026-10-01"
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/forms_summary \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"form": "repair-feedback", "since": "2026-10-01"}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "forms_summary",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.00",
  "balance_usd": "$19.75",
  "result": {
    "form_id": "d4b0d6f7-8211-42b6-ba14-053cca327076",
    "title": "Repair feedback",
    "since": "2026-10-01",
    "responses": 2,
    "fields": [
      {
        "field_id": "nps",
        "question": "How likely are you to recommend us to a friend?",
        "type": "nps",
        "answered": 2,
        "average": 7.5,
        "distribution": [
          {
            "value": 0,
            "count": 0
          },
          {
            "value": 1,
            "count": 0
          }
        ],
        "score": 0.0,
        "promoters": {
          "count": 1,
          "percent": 50.0
        },
        "passives": {
          "count": 0,
          "percent": 0.0
        },
        "detractors": {
          "count": 1,
          "percent": 50.0
        }
      },
      {
        "field_id": "on_time",
        "question": "Was your bike ready on the day we said?",
        "type": "yes_no",
        "answered": 2,
        "yes": {
          "count": 1,
          "percent": 50.0
        },
        "no": {
          "count": 1,
          "percent": 50.0
        }
      }
    ]
  }
}
```

`result`: The form_id, title, since and response count, and per question its results: counts and shares, average and distribution, NPS with promoters and detractors, or the 5 latest text answers.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `not_found` | 404 | No form of the business has that form_id or slug. | Call forms_list and use a form_id or slug from it. |
| `invalid_input` | 400 | since is not an ISO 8601 time or a date. | Send a time like 2026-10-01T00:00:00Z or a date like 2026-10-01. |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [forms_create](https://conecto.chat/tools/forms/forms_create.md): Creates a form or survey with its own public page that anyone can open and answer. $0.01 a call.
- [forms_update](https://conecto.chat/tools/forms/forms_update.md): Changes a form's fields or settings; only what you pass changes. $0.01 a call.
- [forms_get](https://conecto.chat/tools/forms/forms_get.md): One form with its fields, settings, public link, whether it takes responses (and why not) and its response count. Free up to 1,000,000 reads a month.
- [forms_list](https://conecto.chat/tools/forms/forms_list.md): The business's forms, newest first, with their links, whether each takes responses, and their response counts. Free up to 1,000,000 reads a month.
- [forms_list_responses](https://conecto.chat/tools/forms/forms_list_responses.md): A form's responses, newest first, each answer with its question and a readable value. Free up to 1,000,000 reads a month.
- [forms_get_response](https://conecto.chat/tools/forms/forms_get_response.md): One response by its response_id, with every answer readable. Free up to 1,000,000 reads a month.
- [forms_export_responses](https://conecto.chat/tools/forms/forms_export_responses.md): Saves a CSV of a form's responses in the file store and returns a download link. $0.001 a call.
- [forms_close](https://conecto.chat/tools/forms/forms_close.md): Stops a form taking responses; its page then says it is closed. $0.001 a call.
- [forms_open](https://conecto.chat/tools/forms/forms_open.md): Lets a closed form take responses again. $0.001 a call.
- [forms_delete](https://conecto.chat/tools/forms/forms_delete.md): Deletes a form and all its responses for good; its link stops working. $0.001 a call.
- [forms_delete_response](https://conecto.chat/tools/forms/forms_delete_response.md): Deletes one response for good, for a person who asks to be forgotten, or for spam. Free.