Variables

$envless->variables->listHistory()

Read one page of a variable audit trail

php
/** @return Page<VariableHistoryEvent> */
public function listHistory(
    string $project,
    string $environment,
    string $name,
    ?int $limit = null,
    ?int $offset = null,
    ?string $product = null,
    int|float|null $timeout = null,
): Page

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

php
use Envless\Envless;

$envless = new Envless();

$page = $envless->variables->listHistory(
    'api',
    'production',
    'STRIPE_SECRET_KEY',
    limit: 20,
);

foreach ($page->items as $event) {
    echo "{$event['createdAt']} {$event['type']}", PHP_EOL;
}

Parameters

ParameterTypeRequiredDescription
$projectstringYesProject slug the environment belongs to.
$environmentstringYesEnvironment slug the variable lives in.
$namestringYesName of a live variable, matched without regard to case.
$limitintNoPage size between 1 and 100.
$offsetintNoNumber of events to skip before the page starts.
$productstringNoProduct slug, needed when the project slug is not unique in the workspace.
$timeoutint|floatNoSeconds each attempt of this call may take, the response body included, before it throws Envless\Exception\NetworkException with isTimeout() true. 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 an Envless\Result\Page with items and pagination, listAll collects every page into an array, and iterate returns a Generator that yields one item at a time, fetching the next page only when the loop gets there.

Worth knowing

  • actor is 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 historyLimited and hiddenCount flags 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.