---
title: Form responses
description: "Read what came in: a table with a column per question, filters, a detail drawer, a summary with charts and drop-off by question, CSV export, retention, a feed of every form, and submits from your own backend over REST and MCP."
section: cloud
order: 153
audience: [user, operator, builder, agent]
sources: [services/nodejs-cloud/components/forms/responses, services/nodejs-cloud/lib/forms/csv.ts, services/nodejs-cloud/lib/forms/summary.ts, services/nodejs-cloud/lib/forms/http.ts, services/nodejs-cloud/lib/forms/service.ts, docs/adr/0056-venom-forms.md]
features: [cloud.forms]
---

The **Responses** tab (`/forms/{id}?tab=responses`) shows what people submitted. Anyone who can read the form can read its
responses; deleting one needs permission to change forms.

## The numbers

Views, starts, responses and the completion rate (responses over starts), from counters kept per hour.

## Table

One row per response and one column per question, newest first (200 at a time, **Load more** for the rest). Click a row,
or focus it and press Enter, for the detail drawer: every answer in full, hidden fields, computed variables, and a
download link for each file, and **Submitted via**: the API key, OAuth app or member that sent it through the API (with
its id), or **Form page** for a respondent. Once a response from the API is among the loaded rows, the table gets a
Submitted via column too. Delete removes the response and its files for good.

Filters narrow the loaded rows: a text search over every answer and the sender's name or id, a date range (UTC days), and one question with "answer
contains". **Export CSV** downloads what the filters left. The file has a Submitted via column (`API key crm-sync (<key id>)`, `OAuth app
<name> (<client id>)`, `Member <name> (<user id>)`, or `Form page`), a column per question and per hidden field, quotes
properly, carries a byte-order mark so Excel reads the UTF-8, and writes any text that starts with `=`, `+`, `-` or `@` with
a leading apostrophe so a spreadsheet never runs an answer as a formula. Numbers stay numbers.

Without filters the server's export is also there: `GET /forms/api/v1/forms/{id}/export` (up to 50,000 responses).

## Summary

Choice questions show a bar per option with counts and shares; numbers, ratings and scales show the average, lowest and
highest; net promoter score shows the score from −100 to 100; text questions show the latest few answers. **Where
respondents dropped off** shows, for each question, how many of those who started reached it and how many were lost since
the question before; a drop of a fifth or more is highlighted.

## Retention

Settings → Data → *Delete responses older than (days)*. The sweep removes older responses and their files. Empty keeps
them until you delete them.

## Submit from a backend {#submit-from-a-backend}

A backend with a Venom API key (or an app with an OAuth token) that may change forms (`forms:write`) can submit a
response itself, for a signup in your own app or a lead from a partner, without a browser:

```bash
curl -X POST https://cloud.usevenom.dev/forms/api/v1/forms/customer-survey/responses \
  -H "Authorization: Bearer $VENOM_API_KEY" -H "Idempotency-Key: order-4711" \
  -H "content-type: application/json" \
  -d '{"answers": {"name": "Ana", "rating": 5}, "hidden": {"utm_source": "partner"}}'
```

Answers are keyed by block id, hidden fields by their URL parameter, as the form's page sends them. The response goes
through what a person's submit goes through: it is validated against the **published** version (an error names each
question that needs fixing, 422), a draft is refused (409 `not_published`) and so are a closed form, one past its
closing date and one at its response limit (409 `closed`, `ended`, `full`); it counts toward the form's per-minute limit
and has its own, 60 a minute per credential (429 with `Retry-After`); and it is delivered to every destination that is
on. File questions cannot be answered this way: files are uploaded on the form's page. The time trap, the honeypot and
the proof of work are for browsers and do not apply.

The answer (201) is the stored response and `submittedBy`, the key or app that sent it. The form's history records each
one as a `response.submit` entry with that actor, and the response itself keeps it as `submittedVia` (below), so you can
tell these from respondents' own. An `Idempotency-Key`
(or `idempotencyKey` in the body) makes a retry within 24 hours return the first answer instead of storing a second
response. With a [Book a meeting](/docs/cloud/forms-destinations.md#book-a-meeting) destination the answer also carries the
respondent's booking link (`booking`, `redirect`) to pass on. Agents use `forms_response_create`.

## Every form's responses in one feed {#feed}

`GET /forms/api/v1/responses` (or `forms_feed_list`) lists the responses of all your organisation's forms, newest
first, 50 at a time (`limit` up to 200); each row names its form (`formId`, `formTitle`, `formSlug`) and carries a
`feedKey`. Page back with `before=<nextCursor>`. To follow every form from one integration, keep `latest` from your
last call and pass it as `after`: you get the responses submitted since, oldest first, and a new `latest` for the next
poll. A response appears in the feed by its submit time. It needs `forms:read`. The feed reads an index on each
organisation's responses by submit time, so a page costs the same however many responses you keep.

## Who submitted a response {#submitted-via}

Every response in the REST API, the feed, the MCP tools and the CSV carries `submittedVia`: `null` for a respondent on
the form's page, else `{kind, id, name}` with `kind` one of `api_key` (`id` is the key's id, as on the API keys
page), `oauth_client` (the app's OAuth client id) or `session` (a signed-in member calling the REST API from the
console; their user id). It never holds a key, token or secret. A daemon or session named with `x-venom-agent` is
recorded under the key it used. Responses stored before this was recorded (November 2026) show `null`.

## For agents

`forms_response_list` pages through responses with a cursor (and only some block ids with `fields`), `forms_response_summary` returns
the summary, `forms_feed_list` follows every form's responses and `forms_response_create` submits one. REST:
`GET /forms/api/v1/forms/{id}/responses`, `POST …/responses`, `/summary`, `/export`, `DELETE …/responses/{responseId}`,
`GET /forms/api/v1/responses`. See
[Build on Venom Forms](/docs/developers/forms.md).
