Studio Script Reference: Response utilities

context.utils.responses provides a higher-level API for working with Response data sources. It handles tracking own responses, polling for results, and checking vote eligibility — all in a way that works reactively inside computed properties.

All methods take sourceName (the name of the Response data source as a string) and contextId (the ID of the event the user is responding to, typically context.event?.id).

---

canRespond()

Returns true if the user is currently eligible to respond, taking into account the source's configured response interval and response limit.

Reactive — safe to use inside a computed property.

Type: function(sourceName: string, contextId: string): boolean

Example:

// In a computed property:
const canVote = context.utils.responses.canRespond('My poll', context.event?.id);

canRespondCountdown()

Returns how long the user must wait before they can respond again. Useful for showing a cooldown timer.

Reactive — re-evaluates as time passes when used inside a computed.

Type: function(sourceName: string, contextId: string): object

Returns:

{
  value: 5000,    // milliseconds remaining
  days: '0',
  hours: '00',
  minutes: '00',
  seconds: '05'
}

Example:

const countdown = context.utils.responses.canRespondCountdown('My poll', context.event?.id);
// => { value: 5000, days: '0', hours: '00', minutes: '00', seconds: '05' }

fetchResults()

Fetches the current results for a response source and context ID, writes them to an internal reactive ref, and returns the result.

Useful when you need a one-time fetch, or when you want to freeze results at a specific point in time using opts.to.

Type: async function(sourceName: string, contextId: string, opts?: { to?: number }): Promise<object>

Returns:

{
  options: { '0': 42, '1': 58 }, // vote counts per option index
  total: 100
}

Example:

const results = await context.utils.responses.fetchResults('My poll', context.event?.id);

// Freeze results at a specific timestamp:
const frozenResults = await context.utils.responses.fetchResults(
  'My poll',
  context.event?.id,
  { to: 1695931281212 }
);

isFetchingResults()

Returns true if there is an active polling interval running for the given source and context ID.

Type: function(sourceName: string, contextId: string): boolean

Example:

const polling = context.utils.responses.isFetchingResults('My poll', context.event?.id);

ownResponses()

Returns the current user's own responses for a given context ID. Reactive — safe to use inside a computed.

Each response is an object with the submitted value (option index) and a createdAt timestamp.

Type: function(sourceName: string, contextId: string): array

Returns:

[
  { value: 1, createdAt: 1695931281212 }
]

Example:

// In a computed property:
const myAnswers = context.utils.responses.ownResponses('My poll', context.event?.id);
const hasVoted = myAnswers.length > 0;

reset()

Clears both the user's own responses and the fetched results for a given context ID. Also stops any active polling interval.

Type: function(sourceName: string, contextId: string): void

Example:

context.utils.responses.reset('My poll', context.event?.id);

resetResults()

Clears the fetched results for a given context ID, but keeps the user's own responses intact.

Type: function(sourceName: string, contextId: string): void

Example:

context.utils.responses.resetResults('My poll', context.event?.id);

results()

Returns the currently cached results for a given context ID from the internal reactive ref. Does not trigger a fetch — use fetchResults() or startFetchingResults() to populate the data first.

Reactive — safe to use inside a computed.

Type: function(sourceName: string, contextId: string): object | undefined

Example:

// In a computed — will update automatically when results are fetched:
const results = context.utils.responses.results('My poll', context.event?.id);
const winnerIndex = results
  ? Object.entries(results.options).sort((a, b) => b[1] - a[1])[0]?.[0]
  : null;

startFetchingResults()

Starts a polling interval that fetches results on a schedule (using the interval configured on the data source). If a polling interval already exists for the given context ID, it only restarts if the opts have changed.

Type: function(sourceName: string, contextId: string, opts?: { to?: number }): void

Example:

// Start polling — call this when the poll becomes visible:
context.utils.responses.startFetchingResults('My poll', context.event?.id);

stopFetchingResults()

Stops the active polling interval for the given source and context ID.

Type: function(sourceName: string, contextId: string): void

Example:

// Stop polling — call this when the poll is hidden:
context.utils.responses.stopFetchingResults('My poll', context.event?.id);

submit()

Submits a response for an arbitrary event context. The value should be the index of the chosen option in the event's options array.

Unlike context.actions.submitResponse(), this method works for any event ID — not just the currently active one. This makes it suitable for handling multiple polls across a program.

Type: async function(sourceName: string, contextId: string, value: number): Promise<void>

Example:

// Submit a vote for option index 1:
await context.utils.responses.submit('My poll', context.event?.id, 1);