Cursor stability during file edits in Figma REST API pagination

Answer to the Core Question

When a cursor is issued by GET /v1/files/:file_key/components, Figma ties it to the file’s current revision. If the file is modified after that first request, the underlying list changes and the cursor can point to a different slice of the data. In practice this means that the cursor may either skip items that were inserted before the cursor or duplicate items that were deleted after the cursor, depending on the type of edit.

Typical Outcomes Across Endpoints

• /components – Insertions before the cursor usually cause a duplicate of the last seen component; deletions before the cursor skip the deleted component.
• /styles – Similar behaviour; the cursor is not guaranteed to be stable.
• /variables/local – Same pattern; no snapshot pinning is offered.

Detecting Invalidation Without Full Set Comparison

Because the cursor token is opaque, you cannot introspect it. The only reliable signals are:

1. Duplicate id values appear in the aggregated result set.
2. Final count of items differs from the total_count (if provided) or from a pre‑fetched count.

If either of those conditions is met, restart the traversal from the first page.

Practical Steps for a Stable Traversal

1. Store each item in a Map keyed by id to automatically deduplicate.
2. After every next_cursor request, check for duplicate ids. If found, abort and retry from the beginning.
3. Because rate‑limit headers are unreliable, use a fixed 2‑second pause between requests or respect the Retry-After header when present.
4. Optionally, perform a quick /v1/files/:file_key metadata call before starting to capture the file’s last_modified timestamp and compare it after each page to detect edits.

Diagnostic Detail Needed

To fine‑tune the retry logic, please share whether you observe duplicates (same id twice) or gaps (known components missing) after an edit. That determines whether the cursor is shifting forward or backward.