The event feed is a numbered, reliable list of everything that happened to your lab's exports.
The event feed is the backbone of a solid integration. Events get a number, in order, with no gaps, and the feed keeps them for 30 days. Read it from where you left off and you won't miss an event, even after a weekend offline. (A few changes produce no event at all; they're listed below.)
Webhooks are great for reacting quickly. The feed is how you make sure nothing slipped through. Most integrations use both.
curl -s "$API/events?after=$CURSOR&limit=100&wait=30" \
-H "Authorization: Bearer $SPREADU_KEY"after, the feed starts at the oldest event it still keeps.nextCursor as after on your next request.limit is 1 to 200, default 100.wait holds the request open for up to 30 seconds until something happens,
so you get changes quickly without hammering the API.Store nextCursor after every response, also an empty one
A page shorter than limit moves the cursor to the end of the stream, past
events your key can't see or your types filter skips. A full page ends at
its last event, so ask again right away. Save the cursor only after you've
safely processed the page.
A lab can have five live waits per API process. A sixth wait is held for its
wait time and then answered with one read, so an event that arrives meanwhile
reaches it a little later than a live wait would. Closing the connection ends a
wait. Each wait counts as one API request.
Every event has the same envelope: { id, type, version, sequence, occurredAt, data }.
data.export holds the export summary.
export.available also includes the full revision, so you can ask for its
download links straight away.
| Event | What happened |
|---|---|
export.requested | A revision was submitted and is being prepared. |
export.available | A revision is ready to download. |
export.withdrawn | A correction opened or the files became unavailable. Stop producing that revision. |
export.expiring | The revision is getting close to its download deadline. |
export.expired | The download window ended. |
export.confirmed | Your lab confirmed the order identifiers or locked the album. |
export.unlocked | The lab lock was released. |
export.received | Your lab recorded receiving a revision's files. data.revision names it. |
Event bodies are stored when they get their number and are never rewritten.
Events numbered before v1.1 lack the summary and revision fields that version
added, so treat a missing field as unknown. export.received always carries the
full summary. A body never carries fields outside the published schema.
Scopes, enabled modules and an optional types filter decide what a key sees,
so a filtered view can skip numbers. Repeat types for several values, for
example types=export.available&types=export.withdrawn. One value works too.
Only the eight event types above are accepted. Anything else, including ping,
answers 400 BAD_REQUEST.
Events are kept for 30 days after they get their number. 410 CURSOR_EXPIRED
means one of two things:
The fix is the same for both: catch up with GET /exports, then start the feed
again without after.
Test keys and live keys read separate streams. When you switch your application
from a test key to a live key, throw away the test cursor and start the live
feed without after. Don't count on a 410 to catch a test cursor: if its
number happens to fall within the live stream's range, it's accepted, and the
events before it are skipped without an error.
A few changes reach the export without an event. Plan for each:
export.requested is followed by
nothing, and the failed revision never becomes visible. Revision numbers can
skip. Wait for export.available, which names the revision to download.labOrder and moves the summary's updatedAt, without an
event. Poll GET /exports?updatedSince=<last check> to pick them up.GET /exports.Allow analytics to help us improve these docs? We measure page visits and outgoing links. No session recordings. Privacy policy