def iterate_history(
  project,
  environment,
  name,
  limit: nil,
  offset: nil,
  product: nil,
  timeout: nil,
  &block
)

def iterate_history: (
    String project,
    String environment,
    String name,
    ?limit: Integer?,
    ?offset: Integer?,
    ?product: (String | Symbol)?,
    ?timeout: seconds?
  ) -> Enumerator[variable_history_event, nil]
  | (
    String project,
    String environment,
    String name,
    ?limit: Integer?,
    ?offset: Integer?,
    ?product: (String | Symbol)?,
    ?timeout: seconds?
  ) { (variable_history_event) -> void } -> nil

Returns an Enumerator 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

ruby

require "envless/sdk"

Envless.variables.iterate_history(
  "api",
  "production",
  "STRIPE_SECRET_KEY"
) do |event|
  next unless event[:type] == "updated"

  puts "#{event[:createdAt]} #{event[:actor]&.fetch(:email)}"
end

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.
`limit:`	`Integer`	No	Page size for each underlying request, clamped to 100.
`offset:`	`Integer`	No	Offset the walk starts from, defaults to 0.
`product:`	`String \| Symbol`	No	Product slug, needed when the project slug is not unique in the workspace.
`timeout:`	`Integer \| Float \| Rational`	No	Seconds each attempt of this call may take, redirects and the response body included, before it raises `Envless::NetworkError` with `timeout?` set. Overrides the client's `timeout` for this call, and `0` turns the limit off.

Returns

Enumerator[variable_history_event, nil] yielding one audit record per iteration.

Reads the events collection. list returns one page as an Envless::Page with items and pagination, list_all collects every page into an array, and iterate yields one item at a time to a block, fetching the next page only when it gets there. Without a block, iterate returns an Enumerator.

Worth knowing

Event types are created, updated, deleted and restored, so filter on those rather than on dotted names.
On the Free plan only the latest event is yielded (the API's historyLimited and hiddenCount flags 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 TypeScript

envless.variables.iterateHistory()

The same method in @goenvless/sdk, with the same request, retries and errors.

Example#

Parameters#

Returns#

Worth knowing#

Required scopes#

Underlying endpoint#