iterateHistory(project: string, environment: string, name: string, options?: ScopedListOptions): AsyncGenerator<VariableHistoryEvent, void, undefined>Returns an async generator over the audit trail for a variable, fetching the next page only when the current one runs out. Nothing is requested until you begin consuming it.
Breaking out of the loop ends the walk, which makes this the cheap way to scan back to a known point in time. Because new events land at the front of the ordering, a write during a long walk shifts the window and can repeat an event you already saw.
Example
for await (const event of envless.variables.iterateHistory('api', 'production', 'STRIPE_SECRET_KEY')) {
if (event.type === 'updated') console.log(event.createdAt, event.actor?.email)
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project | string | Yes | Project slug the environment belongs to. |
environment | string | Yes | Environment slug the variable lives in. |
name | string | Yes | Name of a live variable, matched without regard to case. |
options.limit | number | No | Page size for each underlying request, clamped to 100. |
options.offset | number | No | Offset the walk starts from, defaults to 0. |
options.product | string | No | Product slug, needed when the project slug is not unique in the workspace. |
options.signal | AbortSignal | No | Cancels the in-flight page request and ends the walk. |
Returns
AsyncGenerator<VariableHistoryEvent, void, undefined> yielding one audit record per iteration.
Reads the events collection. list returns one page as { items, pagination }, listAll collects every page into an array, and iterate streams one item at a time without buffering the whole set.
Worth knowing
- Event types are
created,updated,deletedandrestored, so filter on those rather than on dotted names. - On the Free plan only the latest event is yielded (the API's
historyLimitedandhiddenCountflags are not surfaced by the iterator, so a single event on Free is the plan, not an empty history); the full trail needs Dev or above.
Required scopes
variables:read
Underlying endpoint
GET /projects/{slug}/environments/{environmentSlug}/variables/{name}/history
Request and response schema, every error code, and a live playground.
In Python
envless.variables.iterate_history()
The same method in envless-sdk, the Python SDK, with the same request, retries and errors.
In Ruby
Envless.variables.iterate_history
The same method in envless-sdk, the Ruby gem, with the same request, retries and errors.
In PHP
$envless->variables->iterateHistory()
The same method in envless/sdk, the PHP SDK, with the same request, retries and errors.