Skip to main content
Messages are the detailed, plain-language side of status updates. Use them to give users a readable account of the work in progress. For exact values, combine them with metrics. Messages are AI-generated and can describe both the stage of the roster job and its progress. Each returned item contains Markdown text that you can add to a running feed in your user interface. Show items in the order returned; their exact wording can vary between runs.
Treat message text as display content. Do not use it to determine job state or drive application logic; use status, hasResult, and isActive for that.
Messages are an experimental feature and are only generated for integrators that have been enabled for experimental features.

​
Add detailed updates to your interface

1

Enable messages and choose their language

Set statusOptions.messages.isEnabled to true in your POST /roster/start request. English is used when language is omitted.Also request metrics that reflect what your users care about. They give the AI verified numerical context and can make progress messages more specific. Choose focused scopes rather than every available metric.
Enable messages with a relevant metric
See Metrics for the available metrics and scoping options.
2

Start the roster job

Send the roster start request and retain the returned jobId.

​
Retrieve new messages while polling

Messages form an ordered stream. The status endpoint uses a token to return only the new messages after your previous poll. Tokens are opaque continuation values: do not decode, modify, or construct them. Keep one token per roster job.
1

Initialize message retrieval

Call GET /roster/status/{jobId} without a messageToken. The response contains an empty messages.items array and the first messages.nextToken. Store that token.
2

Request new messages

Pass the stored token as the messageToken query parameter on the next poll. Append every returned item to your interface, then replace the stored token with messages.nextToken.
3

Keep polling

Repeat the previous step while isActive is true. Always store the returned token, even when items is empty, because the token can still advance.
After the first request with a message token, keep polling GET /roster/status/{jobId} until isActive is false. Use isActive, not status, to decide when to stop polling. Always make that first token-bearing request, even if the initialization response already has isActive: false, so messages from a fast job are still retrieved.
This example shows how the token moves across multiple polls. Token values are shortened for readability.
Persist the latest token with the job if polling can move between processes or resume after an application restart. Reusing an older token can return messages you have already received.