For DevelopersAPI

List responses

Fetch and paginate survey responses as JSON or RSS.

GET https://app.tinydialog.com/api/v1/responses

This endpoint requires an API key. Responses are ordered from newest to oldest, by timestamp and then response ID.

Query parameters

ParameterDescriptionDefault
formatjson or rss.json
limitInteger from 1 to 50.25
cursorContinuation cursor from a previous page.First page
projectIdRead responses from one accessible project.All accessible projects
surveyIdRead responses from one accessible survey.All accessible surveys
tokenAPI key, as an alternative to the Authorization header.None

Set either projectId or surveyId. Setting both returns 400. Omit both for account-wide responses from all organizations you belong to. A project or survey outside your account returns the same 404 as an ID that does not exist.

Empty IDs, invalid values, duplicate parameters, unknown parameters, and invalid cursors return 400.

JSON

curl --get 'https://app.tinydialog.com/api/v1/responses' \
  --header "Authorization: Bearer $TINYDIALOG_API_TOKEN" \
  --data-urlencode 'projectId=YOUR_PROJECT_ID' \
  --data-urlencode 'limit=10'

The response has content type application/json:

{
  "data": [
    {
      "id": 123,
      "timestamp": "2026-11-16T10:30:00.000Z",
      "response": { "type": "single", "value": "The new design is easy to use." },
      "project": {
        "id": "project-id",
        "name": "My Website",
        "organization": { "id": "organization-id", "name": "My Organization" }
      },
      "survey": { "id": "survey-id", "name": "Feedback" },
      "respondent": {
        "contact": null,
        "url": "https://example.com/",
        "operatingSystem": "macOS",
        "browser": "Safari",
        "screenSize": "1440x900"
      },
      "extraData": null,
      "topics": null,
      "screenshotUrl": null
    }
  ],
  "pagination": {
    "limit": 10,
    "nextCursor": "eyJraW5kIjoicmVzcG9uc2UiLCJ0aW1lc3RhbXAiOjE3OTQ4MjUwMDAwMDAsImlkIjoxMjN9"
  }
}

response.value can be a string, boolean, or number, depending on the survey. Respondent fields, extra data, topics, and screenshots can be null. Screenshot URLs expire after five minutes. Respondent IP addresses are not included.

An empty result has data: [] and pagination.nextCursor: null.

Pagination

Pass pagination.nextCursor unchanged as cursor to read the next page. Keep the same project or survey filter and authenticate every request:

curl --get 'https://app.tinydialog.com/api/v1/responses' \
  --header "Authorization: Bearer $TINYDIALOG_API_TOKEN" \
  --data-urlencode 'projectId=YOUR_PROJECT_ID' \
  --data-urlencode 'limit=10' \
  --data-urlencode "cursor=$NEXT_CURSOR"

Stop when nextCursor is null. The cursor uses the CLI response API's timestamp and ID ordering, including an ID tie-breaker for responses with the same timestamp.

Cursors must reference an existing response that you can access within the selected filter. Cursors from another account or outside that filter are rejected. Modified or deleted cursor responses can invalidate a cursor; start again without cursor if this occurs. Treat cursors as opaque values.

RSS

Set format=rss to receive an RSS 2.0 feed with content type application/rss+xml:

curl --get 'https://app.tinydialog.com/api/v1/responses' \
  --header "Authorization: Bearer $TINYDIALOG_API_TOKEN" \
  --data-urlencode 'format=rss' \
  --data-urlencode 'surveyId=YOUR_SURVEY_ID'

Each item contains the project and survey names, response value, submission date, a stable GUID, and a dashboard link. Submitted text is escaped for safe display in feed readers. RSS uses the same filters, limits, and pagination as JSON.

When more results exist, the feed includes an Atom link with rel="next" and an HTTP Link header with rel="next". These URLs contain the next cursor. Feed links do not include API keys. Authenticate again when following a link; if you use query authentication, add your token parameter again.

To see new responses, refresh the original feed URL without a cursor.

Errors

Errors are JSON, including when you request RSS:

{
  "error": {
    "code": "invalid_cursor",
    "message": "Cursor is invalid or does not belong to the selected scope."
  }
}
StatusMeaning
400Invalid query parameters, ambiguous credentials, or an invalid cursor.
401Missing, invalid, expired, disabled, revoked, or insufficiently permitted API key.
404Project or survey does not exist or is inaccessible.
429Rate limit exceeded. Observe the Retry-After header.
500Unexpected server error.
503Rate limiter is unavailable. Try again later.

Last updated on

On this page