listHistory(project: string, environment: string, name: string, options?: ScopedListOptions): Promise<Page<VariableHistoryEvent>>Fetches one page of the audit trail for a variable, newest event first.
These are VariableHistoryEvent audit records, not past values of the variable. No value is ever included, ciphertext or otherwise. metadata carries small change hints such as nameChanged, valueChanged, previousName, rolledBackFromVersion or source, and its keys differ per event type, so read it defensively.
History is recorded against the variable id, so it follows the row through renames but does not follow a name. A name that was deleted and created again starts a fresh id with an empty trail.
Example
const page = await envless.variables.listHistory('api', 'production', 'STRIPE_SECRET_KEY', { limit: 20 })
for (const event of page.items) console.log(event.createdAt, event.type)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 between 1 and 100. |
options.offset | number | No | Number of events to skip before the page starts. |
options.product | string | No | Product slug, needed when the project slug is not unique in the workspace. |
options.signal | AbortSignal | No | Cancels the request. |
Returns
Page<VariableHistoryEvent> whose items come from the response collection events.
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
actoris null when the change came from an internal process or from a key whose owner record is gone.- The variable must still be live. History for a deleted variable is not reachable through this route.
- On the Free plan only the latest event is returned (the API's
historyLimitedandhiddenCountflags are not surfaced on the SDK page, so a one-item result 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.list_history()
The same method in envless-sdk, the Python SDK, with the same request, retries and errors.
In Ruby
Envless.variables.list_history
The same method in envless-sdk, the Ruby gem, with the same request, retries and errors.
In PHP
$envless->variables->listHistory()
The same method in envless/sdk, the PHP SDK, with the same request, retries and errors.