def list_history(
project: str,
environment: str,
name: str,
*,
limit: int | None = None,
offset: int | None = None,
product: str | None = None,
timeout: float | None = None,
) -> Page[VariableHistoryEvent]async def list_history(
project: str,
environment: str,
name: str,
*,
limit: int | None = None,
offset: int | None = None,
product: str | None = None,
timeout: float | None = None,
) -> 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
from envless import envless
page = envless.variables.list_history(
'api', 'production', 'STRIPE_SECRET_KEY', limit=20
)
for event in page['items']:
print(event['createdAt'], event['type'])import asyncio
from envless import AsyncEnvless
async def main() -> None:
async with AsyncEnvless() as envless:
page = await envless.variables.list_history(
'api', 'production', 'STRIPE_SECRET_KEY', limit=20
)
for event in page['items']:
print(event['createdAt'], event['type'])
asyncio.run(main())Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project | str | Yes | Project slug the environment belongs to. |
environment | str | Yes | Environment slug the variable lives in. |
name | str | Yes | Name of a live variable, matched without regard to case. |
limit | int | No | Page size between 1 and 100. |
offset | int | No | Number of events to skip before the page starts. |
product | str | No | Product slug, needed when the project slug is not unique in the workspace. |
timeout | float | No | Seconds each attempt of this call may take, the response body included, before it raises EnvlessNetworkError with is_timeout set. Overrides the client's timeout for this call, and 0 turns the limit off. |
Returns
Page[VariableHistoryEvent] whose items come from the response collection events.
Reads the events collection. list returns one page as a dict with items and pagination, list_all collects every page into a list, and iterate yields one item at a time, fetching the next page only when the loop reaches it. On AsyncEnvless, iterate is an async iterator for async for.
Worth knowing
actorisNonewhen 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 TypeScript
envless.variables.listHistory()
The same method in @goenvless/sdk, with the same request, retries and errors.