Document Visibility scope, consistency, and rate-limited APIs - #4995
Open
austonli wants to merge 11 commits into
Open
Document Visibility scope, consistency, and rate-limited APIs#4995austonli wants to merge 11 commits into
austonli wants to merge 11 commits into
Conversation
Make the customer-facing Visibility docs opinionated about what Visibility is for as usage scales, and complete the reference for which APIs it covers. - visibility.mdx: add "Operations that use Visibility", "How current is Visibility data", and "When to use Visibility" sections. - limits.mdx: replace the catch-all sentence in the Visibility API Rate Limit section with the full, categorized list of covered APIs, and clarify that single-entity lookups by ID do not count against it. - schedule.mdx: note that ListSchedules/CountSchedules are Visibility APIs, sharing its rate limit and eventual consistency. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
📖 Docs PR preview links
|
Remove the "usually a couple of seconds, longer under load" wording from "How current is Visibility data." It understated real Cloud latency, misattributed the cause to load, and read as a commitment Cloud does not make. Replace with variable-delay framing and an explicit note that Cloud publishes no SLA for visibility freshness, linking /cloud/sla. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
brianmacdonald-temporal
left a comment
brianmacdonald-temporal
left a comment
Contributor
There was a problem hiding this comment.
Added some links and tightened some wording.
We may need some additional approvals on the Limits page. I'll determine who to tap.
|
|
||
| ## How current is Visibility data | ||
|
|
||
| Visibility is a search index that Temporal updates asynchronously. After a change is recorded, it takes some time to propagate to the index, so a List or Count query can briefly return stale results. This propagation delay is variable. It is usually fast, but it can be several seconds or longer, and Temporal Cloud does not publish an [SLA](/cloud/sla) for how quickly changes become visible. Treat Visibility as eventually consistent and avoid depending on a fixed or guaranteed delay. |
Contributor
There was a problem hiding this comment.
I think we may need to get some official guidance on how we talk about the propagation delay in this paragraph, to make sure we don't introduce legal issues.
bechols
approved these changes
Jul 30, 2026
Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>
Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>
Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>
Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>
Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>
Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>
Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>
Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>
Contributor
❌ Docs build failedBroken anchorsThe target page exists, but the heading/anchor it links to doesn't. Fix the anchor, or add the missing heading to the target page.
Run |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Makes the customer-facing Visibility docs opinionated about what Visibility is for as usage scales, and completes the reference for which APIs are subject to the Visibility API rate limit.
encyclopedia/visibility/visibility.mdxAdds three sections between "Visibility features" and "Legacy: standard Visibility":
ListSchedules/CountSchedules,ListBatchOperations, reachability), and clarifies that single-entity lookups by ID do not.DescribeWorkflowExecutionfor authoritative single-execution state.evaluate/temporal-cloud/limits.mdxReplaces the catch-all sentence in the Visibility API Rate Limit section with the full categorized list of covered APIs, and corrects the implication that all read calls count (single-entity lookups by ID read the primary store and count against the general namespace RPS).
encyclopedia/workflow/schedule.mdxNotes that
ListSchedules/CountSchedulesare served by Visibility, sharing its rate limit and eventual consistency. Per-SDK "list schedules" sections keep their existing consistency note.Why
As customers run Visibility at higher scale and for new use cases, several innocuously-named APIs (notably
ListSchedules) turn out to be Visibility queries under the hood, subject to a separate rate limit and eventual consistency. Today the docs don't say which APIs use Visibility, don't document the consistency model, and don't guide customers on what Visibility is and isn't the right tool for. This makes that explicit.Review notes
#operations-that-use-visibility,#how-current-is-visibility-data,#when-to-use-visibility; cross-links to/cloud/limits#visibility-api-rate-limitand/visibility#operations-that-use-visibilityresolve.🤖 Generated with Claude Code
┆Attachments: EDU-6849 Document Visibility scope, consistency, and rate-limited APIs