> ## Documentation Index > Fetch the complete documentation index at: https://docs.usertick.com/llms.txt > Use this file to discover all available pages before exploring further. # List recent responses > The newest responses in the shape a webhook of the same event carries in data (a trigger's sample). response.created describes each response without its analysis; response.analyzed returns only analyzed ones and response.urgent only those whose urgency reads high, filtered the way a subscription is; response.status_changed returns the newest status changes (a response that changed twice is listed twice), each with its change. response.classification_corrected and theme.spiking have no list (400 APK-006-012). One page; limit 1 to 100, default 3. A sample, not a full list: it looks through the newest 1,000 responses (or status changes) in the plan's window and stops there, so a filter that matches only older ones answers fewer than limit. GET /responses lists every response. Scopes: responses:read. ## OpenAPI ````yaml api-reference/openapi.json GET /responses/recent openapi: 3.1.0 info: title: Usertick Public API version: 1.0.0 description: >- The Usertick REST API v1: responses, surveys, metrics and webhook subscriptions of one organization. **Authentication.** Send an API key (Settings, Developers, API keys; utk_...) or an app's OAuth access token (uto_...) as Authorization: Bearer. X-Api-Key works for clients that cannot set Authorization. Each endpoint lists the scopes it needs. API keys work on Pro plans and up, and apps such as Zapier on Starter plans and up. **Format.** Plain JSON resources; times are RFC 3339 in UTC with milliseconds (2026-09-30T10:00:00.000Z). Lists are { data, nextCursor }: limit is 1 to 100 (default 25, out of range is 400), and nextCursor goes back as cursor until it is null. A page starts strictly after the last row of the page before, so a row deleted or renamed in between never ends a list early. **Errors.** Every error is { statusCode, success: false, code, message, data }, plus errors: [{ field, code, message }] for invalid fields. Switch on code (x-error-codes lists them all); messages may change. **Rate limits.** 120 requests a minute per credential and 600 per organization, as token buckets. An answer to an authenticated request has X-RateLimit-Limit, -Remaining and -Reset (seconds until the budget is full) for the credential, and X-RateLimit-Org-* for the organization, except a 429 over the credential's budget, which has the credential's only. Over a budget is 429 with Retry-After. A 401 carries no X-RateLimit headers, and neither does a 429 GEN-429-001 from the per-address limit (3,000 requests a minute per client address, checked before the credential). **Idempotency.** Every POST takes an Idempotency-Key header: the same key and request within 24 hours get the first answer again. **Versioning.** Within /v1 changes are additive only: new endpoints, new optional parameters, new fields (ignore fields you do not know). Anything that will go away is announced at least six months ahead with Deprecation and Sunset headers on its answers. **Webhooks.** Every delivery is { id, type, createdAt, data }, signed per Standard Webhooks (see webhooks). data is the Response resource, with change on response.status_changed and response.classification_corrected; on theme.spiking it is the spike. Every answer carries X-Request-Id. contact: name: Usertick support url: https://usertick.com/support servers: - url: https://app.usertick.com/api/public/v1 description: Production security: - bearerAuth: [] - apiKeyHeader: [] tags: - name: Account - name: Responses - name: Surveys - name: Metrics - name: Webhooks paths: /responses/recent: get: tags: - Responses summary: Newest responses as a webhook carries them description: >- The newest responses in the shape a webhook of the same event carries in data (a trigger's sample). response.created describes each response without its analysis; response.analyzed returns only analyzed ones and response.urgent only those whose urgency reads high, filtered the way a subscription is; response.status_changed returns the newest status changes (a response that changed twice is listed twice), each with its change. response.classification_corrected and theme.spiking have no list (400 APK-006-012). One page; limit 1 to 100, default 3. A sample, not a full list: it looks through the newest 1,000 responses (or status changes) in the plan's window and stops there, so a filter that matches only older ones answers fewer than limit. GET /responses lists every response. Scopes: responses:read. operationId: listRecentResponses parameters: - name: event in: query description: >- response.created (default), response.analyzed, response.status_changed or response.urgent. required: false schema: type: string enum: - response.created - response.analyzed - response.status_changed - response.urgent - name: surveyId in: query description: One survey. required: false schema: type: string format: uuid - name: types in: query description: >- Feedback types (repeat, or comma separated); not with response.created. required: false schema: type: array items: type: string enum: - bug - idea - complaint - question - praise style: form explode: true - name: urgencies in: query description: Urgency bands; response.analyzed and response.status_changed. required: false schema: type: array items: type: string enum: - high - medium - low style: form explode: true - name: themes in: query description: Theme ids (GET /themes); not with response.created. required: false schema: type: array items: type: string format: uuid style: form explode: true - name: limit in: query description: 1 to 100, default 3. required: false schema: type: integer minimum: 1 maximum: 100 default: 3 responses: '200': description: The responses; on response.status_changed each carries change. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' X-RateLimit-Org-Limit: $ref: '#/components/headers/XRateLimitOrgLimit' X-RateLimit-Org-Remaining: $ref: '#/components/headers/XRateLimitOrgRemaining' X-RateLimit-Org-Reset: $ref: '#/components/headers/XRateLimitOrgReset' content: application/json: schema: $ref: '#/components/schemas/ResponseList' '400': description: >- The request isn't valid. Codes: PUB-001-001, APK-006-001, APK-006-002, APK-006-003, APK-006-004, APK-006-010, APK-006-011, APK-006-012. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: PUB-001-001: $ref: '#/components/examples/PUB-001-001' APK-006-001: $ref: '#/components/examples/APK-006-001' APK-006-002: $ref: '#/components/examples/APK-006-002' APK-006-003: $ref: '#/components/examples/APK-006-003' APK-006-004: $ref: '#/components/examples/APK-006-004' APK-006-010: $ref: '#/components/examples/APK-006-010' APK-006-011: $ref: '#/components/examples/APK-006-011' APK-006-012: $ref: '#/components/examples/APK-006-012' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: 'The resource couldn''t be found. Codes: APK-006-005.' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: APK-006-005: $ref: '#/components/examples/APK-006-005' '429': $ref: '#/components/responses/TooManyRequests' '503': description: 'A data store didn''t respond. Try again. Codes: RSP-001-001.' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: RSP-001-001: $ref: '#/components/examples/RSP-001-001' components: headers: XRequestId: description: >- This answer's id (req_ and 32 hex characters), also in the logs. Quote it to support. schema: type: string XRateLimitLimit: description: The credential's requests per minute. schema: type: integer XRateLimitRemaining: description: What is left of it now. schema: type: integer XRateLimitReset: description: >- Seconds until the credential's budget is full again (the bucket refills continuously). schema: type: integer XRateLimitOrgLimit: description: Every credential of the organization together, per minute. schema: type: integer XRateLimitOrgRemaining: description: What is left of the organization's budget. schema: type: integer XRateLimitOrgReset: description: Seconds until the organization's budget is full again. schema: type: integer RetryAfter: description: Seconds to wait before trying again. schema: type: integer schemas: ResponseList: type: object properties: data: type: array items: $ref: '#/components/schemas/Response' nextCursor: type: - string - 'null' description: Send it back as cursor for the next page; null on the last page. required: - data - nextCursor description: A page of responses. additionalProperties: false Error: type: object properties: statusCode: type: integer description: The HTTP status, again. success: type: boolean description: Always false. code: type: string description: >- What went wrong, stable across versions (see x-error-codes). For invalid fields, the first field's code. examples: - PUB-001-001 message: type: - string - 'null' description: The code's message in English (US); null for a code without one. data: description: Extra context for some errors; null otherwise. errors: type: array items: $ref: '#/components/schemas/FieldError' description: >- Every invalid field, in the order of the request's parameters. Only on a 400 about fields. required: - statusCode - success - code - message - data description: >- Every error answer. Success answers are the plain resource or list instead. additionalProperties: false examples: - statusCode: 400 success: false code: PUB-001-001 message: The limit must be between 1 and 100. data: null errors: - field: limit code: PUB-001-001 message: The limit must be between 1 and 100. - field: sort code: PUB-001-005 message: The sort order must be asc or desc. Response: type: object properties: id: type: string description: The response's id (a UUID). format: uuid url: type: string description: The response in the Usertick inbox. format: uri survey: $ref: '#/components/schemas/SurveyRef' site: oneOf: - $ref: '#/components/schemas/SiteRef' - type: 'null' createdAt: type: string format: date-time examples: - '2026-09-30T10:00:00.000Z' description: When the response was received. updatedAt: type: string format: date-time examples: - '2026-09-30T10:00:00.000Z' description: >- The latest of: received, analyzed, and the last change a person or an integration made (status, type, urgency, assignees, notes, corrections). source: type: - string - 'null' description: widget, link, email or api. language: type: - string - 'null' country: type: - string - 'null' description: ISO 3166-1 alpha-2. pageUrl: type: - string - 'null' description: The page the response was sent from. device: oneOf: - $ref: '#/components/schemas/Device' - type: 'null' variant: type: - string - 'null' description: >- The ID of the survey variant the respondent saw (v_ followed by letters and digits); null when the respondent saw the survey without a variant. variantName: type: - string - 'null' description: >- The name of that variant, also for a variant the survey no longer has; null when variant is null or the variant has no name. contact: oneOf: - $ref: '#/components/schemas/ContactRef' - type: 'null' respondent: $ref: '#/components/schemas/Respondent' answers: type: array items: $ref: '#/components/schemas/Answer' description: >- Answered questions in survey order; answers to questions the survey no longer has come last. answerText: type: object description: Question id to the answer's display text. additionalProperties: type: string attachments: type: array items: $ref: '#/components/schemas/Attachment' status: type: string enum: - open - planned - in_progress - resolved - archived assignees: type: array items: $ref: '#/components/schemas/Assignee' ai: oneOf: - $ref: '#/components/schemas/Ai' - type: 'null' commentsCount: type: integer description: Notes on the timeline, deleted ones not counted. required: - id - url - survey - site - createdAt - updatedAt - source - language - country - pageUrl - device - variant - variantName - contact - respondent - answers - answerText - attachments - status - assignees - ai - commentsCount description: >- One response: what every response read returns and what every webhook delivery carries in data. additionalProperties: false examples: - id: 9b1c2d3e-4f50-4a61-8b72-93a4b5c6d7e8 url: https://app.usertick.com/inbox/9b1c2d3e-4f50-4a61-8b72-93a4b5c6d7e8 survey: id: 11111111-1111-4111-8111-111111111111 name: Checkout feedback site: id: 22222222-2222-4222-8222-222222222222 domain: shop.example.com createdAt: '2026-09-30T10:00:00.123Z' updatedAt: '2026-09-30T12:31:05.120Z' source: widget language: en country: US pageUrl: https://shop.example.com/checkout device: type: desktop browser: Chrome os: macOS variant: null variantName: null contact: id: 77777777-7777-4777-8777-777777777777 email: maya@example.com respondent: userId: user_8271 anonymousId: 5f0c7a2b-8d4e-4c1a-9e3f-2b6d8a0c4e1f verified: true email: maya@example.com emailSource: identify name: Maya Chen company: Example Inc. traits: company: Example Inc. plan: pro traitsVerified: false contactQuestion: null contact: id: 77777777-7777-4777-8777-777777777777 answers: - questionId: q_nps question: How likely are you to recommend us? type: nps value: 4 text: '4' - questionId: q_comment question: What went wrong? type: text value: Checkout rejects my card every time text: Checkout rejects my card every time answerText: q_nps: '4' q_comment: Checkout rejects my card every time attachments: [] status: in_progress assignees: - id: 66666666-6666-4666-8666-666666666666 name: Ana Ruiz email: ana@example.com ai: type: bug urgency: high theme: id: 44444444-4444-4444-8444-444444444444 name: Checkout errors category: id: 55555555-5555-4555-8555-555555555555 name: Payments sentiment: negative analyzedAt: '2026-09-30T10:00:07.250Z' corrected: false commentsCount: 2 FieldError: type: object properties: field: type: string description: >- The query parameter, or the body property (camelCase, dotted when nested). code: type: string message: type: - string - 'null' required: - field - code - message additionalProperties: false SurveyRef: type: object properties: id: type: string format: uuid name: type: - string - 'null' description: >- The survey's name. Responses of a deleted survey are left out of every read and delivery, so it is null only when the survey is deleted while the response is being read. required: - id - name additionalProperties: false SiteRef: type: object properties: id: type: string format: uuid domain: type: string required: - id - domain additionalProperties: false Device: type: object properties: type: type: - string - 'null' enum: - desktop - tablet - mobile - null browser: type: - string - 'null' os: type: - string - 'null' required: - type - browser - os additionalProperties: false ContactRef: type: object properties: id: type: - string - 'null' format: uuid description: >- The Usertick contact the response is linked to; null when it is linked to none. email: type: - string - 'null' description: >- The linked contact's email, else the respondent's (respondent.email). format: email required: - id - email description: Who answered, when known; null when nothing names them. additionalProperties: false Respondent: type: object properties: userId: type: - string - 'null' description: >- The customer's own user id, as the site's widget sent it (Usertick.identify). anonymousId: type: - string - 'null' description: >- The browser's random visitor id; a new one after logout. Null when none came. verified: type: boolean description: >- A valid user hash, computed by the customer's server, came with the response. email: type: - string - 'null' description: >- The respondent's email, by precedence: the email campaign's contact, a verified identify email, the contact question (or an answer that is exactly an address), an unverified identify email. format: email emailSource: type: - string - 'null' description: Where email came from. enum: - identify - contact_question - campaign - null name: type: - string - 'null' description: The name identify sent. company: type: - string - 'null' description: The company identify sent. traits: type: object description: >- The other traits identify sent, a flat object of strings, numbers and booleans; empty without any. additionalProperties: type: - string - number - boolean traitsVerified: type: boolean description: The traits came with a verified user id. contactQuestion: type: - object - 'null' description: >- What the respondent typed into a contact question: the fields it asked for that have a value (name, email, phone, company, message). Null without one. additionalProperties: type: string contact: oneOf: - type: object properties: id: type: string format: uuid required: - id additionalProperties: false - type: 'null' description: The Usertick contact the response is linked to. required: - userId - anonymousId - verified - email - emailSource - name - company - traits - traitsVerified - contactQuestion - contact description: >- Who answered. Always present; a field is null when unknown. Never sent to the AI. additionalProperties: false Answer: type: object properties: questionId: type: string question: type: - string - 'null' description: Null for a question the survey no longer has. type: type: - string - 'null' value: description: >- The answer as sent: a number, a string, a boolean, an array or an object. text: type: string description: The answer as a person reads it. required: - questionId - question - type - value - text additionalProperties: false Attachment: type: object properties: id: type: string questionId: type: string name: type: string url: type: string description: >- GET it with a credential that has responses:read: the API answers 302 to a download link valid for 5 minutes. format: uri required: - id - questionId - name - url additionalProperties: false Assignee: type: object properties: id: type: string format: uuid description: The member id (GET /members). name: type: - string - 'null' email: type: - string - 'null' format: email required: - id - name - email additionalProperties: false Ai: type: object properties: type: type: - string - 'null' enum: - bug - idea - complaint - question - praise - null urgency: type: - string - 'null' enum: - high - medium - low - null theme: oneOf: - $ref: '#/components/schemas/TaxonomyRef' - type: 'null' category: oneOf: - $ref: '#/components/schemas/TaxonomyRef' - type: 'null' sentiment: type: - string - 'null' enum: - negative - neutral - positive - null analyzedAt: type: - string - 'null' format: date-time examples: - '2026-09-30T10:00:00.000Z' description: When the analysis ran; null when it is not known. corrected: type: boolean description: A person changed one of these values; it wins over the analysis. required: - type - urgency - theme - category - sentiment - analyzedAt - corrected description: >- The analysis. Null until analyzed, when the analysis was skipped or failed and nobody corrected it, and on every response.created delivery. additionalProperties: false TaxonomyRef: type: object properties: id: type: string format: uuid name: type: string required: - id - name additionalProperties: false examples: PUB-001-001: summary: The limit must be between 1 and 100. value: statusCode: 400 success: false code: PUB-001-001 message: The limit must be between 1 and 100. data: null APK-006-001: summary: >- The event isn't recognized. Use response.created, response.analyzed, response.status_changed, response.classification_corrected, response.urgent, theme.spiking or workflow.step. value: statusCode: 400 success: false code: APK-006-001 message: >- The event isn't recognized. Use response.created, response.analyzed, response.status_changed, response.classification_corrected, response.urgent, theme.spiking or workflow.step. data: null APK-006-002: summary: >- This event doesn't accept these filters. response.created accepts none, response.urgent doesn't accept urgency, and theme.spiking accepts only themes. value: statusCode: 400 success: false code: APK-006-002 message: >- This event doesn't accept these filters. response.created accepts none, response.urgent doesn't accept urgency, and theme.spiking accepts only themes. data: null APK-006-003: summary: >- The feedback type isn't recognized. Use bug, idea, complaint, question or praise. The type filter of GET /responses also takes none. value: statusCode: 400 success: false code: APK-006-003 message: >- The feedback type isn't recognized. Use bug, idea, complaint, question or praise. The type filter of GET /responses also takes none. data: null APK-006-004: summary: The urgency isn't recognized. Use high, medium or low. value: statusCode: 400 success: false code: APK-006-004 message: The urgency isn't recognized. Use high, medium or low. data: null APK-006-010: summary: The theme isn't recognized. Use theme IDs from GET /themes. value: statusCode: 400 success: false code: APK-006-010 message: The theme isn't recognized. Use theme IDs from GET /themes. data: null APK-006-011: summary: Filter by at most 5,000 themes. value: statusCode: 400 success: false code: APK-006-011 message: Filter by at most 5,000 themes. data: null APK-006-012: summary: >- This event has no recent list. Use response.created, response.analyzed, response.status_changed or response.urgent. value: statusCode: 400 success: false code: APK-006-012 message: >- This event has no recent list. Use response.created, response.analyzed, response.status_changed or response.urgent. data: null APK-006-005: summary: The survey couldn't be found. value: statusCode: 404 success: false code: APK-006-005 message: The survey couldn't be found. data: null RSP-001-001: summary: Responses can't be loaded right now. Try again in a moment. value: statusCode: 503 success: false code: RSP-001-001 message: Responses can't be loaded right now. Try again in a moment. data: null APK-004-001: summary: Send an API key or an access token in the Authorization header. value: statusCode: 401 success: false code: APK-004-001 message: Send an API key or an access token in the Authorization header. data: null APK-004-002: summary: >- The API key or access token is invalid, expired or revoked. Connect again with a valid one. value: statusCode: 401 success: false code: APK-004-002 message: >- The API key or access token is invalid, expired or revoked. Connect again with a valid one. data: null APK-004-004: summary: >- This API key or app doesn't have permission for this request. Grant it the required scope. value: statusCode: 403 success: false code: APK-004-004 message: >- This API key or app doesn't have permission for this request. Grant it the required scope. data: null APK-004-005: summary: >- Your plan doesn't include API keys or the MCP server. To use them, upgrade to Pro or higher. value: statusCode: 403 success: false code: APK-004-005 message: >- Your plan doesn't include API keys or the MCP server. To use them, upgrade to Pro or higher. data: null APK-004-008: summary: >- Your plan doesn't include apps that use the API, such as Zapier. To use them, upgrade to Starter or higher. value: statusCode: 403 success: false code: APK-004-008 message: >- Your plan doesn't include apps that use the API, such as Zapier. To use them, upgrade to Starter or higher. data: null AUTHZ-001-002: summary: Your role doesn't have the required permission. value: statusCode: 403 success: false code: AUTHZ-001-002 message: Your role doesn't have the required permission. data: null APK-004-003: summary: This API key or app sent too many requests. Wait a minute and try again. value: statusCode: 429 success: false code: APK-004-003 message: >- This API key or app sent too many requests. Wait a minute and try again. data: null APK-004-006: summary: >- Your organization sent too many API requests. Wait a minute and try again. value: statusCode: 429 success: false code: APK-004-006 message: >- Your organization sent too many API requests. Wait a minute and try again. data: null GEN-429-001: summary: Too many requests were sent. Wait a minute and try again. value: statusCode: 429 success: false code: GEN-429-001 message: Too many requests were sent. Wait a minute and try again. data: null responses: Unauthorized: description: >- No credential, or one that is invalid, expired or revoked. Codes: APK-004-001, APK-004-002. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: APK-004-001: $ref: '#/components/examples/APK-004-001' APK-004-002: $ref: '#/components/examples/APK-004-002' Forbidden: description: >- The credential lacks a scope this endpoint needs, the plan does not include the API (API keys on Pro and up, apps such as Zapier on Starter and up), or an app's member lacks the permission. Codes: APK-004-004, APK-004-005, APK-004-008, AUTHZ-001-002. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: APK-004-004: $ref: '#/components/examples/APK-004-004' APK-004-005: $ref: '#/components/examples/APK-004-005' APK-004-008: $ref: '#/components/examples/APK-004-008' AUTHZ-001-002: $ref: '#/components/examples/AUTHZ-001-002' TooManyRequests: description: >- Over the credential's or the organization's budget, or over the per-address limit that is checked before the credential (GEN-429-001, without X-RateLimit headers). Codes: APK-004-003, APK-004-006, GEN-429-001. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' examples: APK-004-003: $ref: '#/components/examples/APK-004-003' APK-004-006: $ref: '#/components/examples/APK-004-006' GEN-429-001: $ref: '#/components/examples/GEN-429-001' securitySchemes: bearerAuth: type: http scheme: bearer description: An API key (utk_live_...) or an app's OAuth access token (uto_...). apiKeyHeader: type: apiKey in: header name: X-Api-Key description: The API key, for clients that cannot send Authorization. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.