Instruction

Properties

instruction_id string
Unique identifier of the instruction.

organization_id string
The organization that owns this instruction.

module_id string
The module this instruction executes against (module_type discriminates the domain). Derived from the policy at creation time for product-module instructions. The code actually executed is always the latest live definition for this module (not pinned to a specific version).

module_type string
The module type the instruction executes against. product_module instructions are policy-derived (the module is resolved from the policy). collection_module is reserved for upcoming collection-module support — creating a collection_module instruction is currently rejected with 400.

policy_id string,null
The policy this instruction is associated with. Always set for product-module instructions.

claim_id string,null
The claim this instruction is associated with, if any. When set, the claim must belong to policy_id.

execution_datetime string
ISO 8601 datetime when the instruction should execute, stored and returned in UTC. Must fall on a 30-minute boundary (e.g. 2026-06-01T14:00:00.000Z or 2026-06-01T14:30:00.000Z) and at least 15 minutes in the future at creation time.

status string
The lifecycle status of the instruction.
pending — created but not yet picked up by the scheduler
queued — the scheduler has dispatched it to the execution queue
executed — the function has been invoked
successful — the function executed without error
failed — the function threw an error
cancelled — manually cancelled before execution

module object
Free-form payload passed to the product module function as instruction_data when the instruction executes.

function_name string
The name of the product module function to invoke at execution_datetime. The function must be exported from the product module's published code.

description string,null
Optional human-readable description of what this instruction does. Useful for debugging and dashboards.

environment string
The environment the instruction was created in.

hidden boolean
When true, this instruction is filtered out of standard listings. Requires the instructions:read_hidden permission to view. Used for internal platform-generated instructions.

manually_executable boolean
When true, the instruction can be triggered via POST /instructions/{instruction_id}/trigger before its execution_datetime. When false, it can only run via the scheduled job.

created_at string
When the instruction was created.

created_by object
Describes the actor that performed an action.

type string
The actor type (e.g. user, product_module, system).

id string
The unique identifier of the actor.

owner_id string
The organization the actor belongs to.

user_group_id string
The user group the actor is scoped to, where applicable.

updated_at string
When the instruction was last modified.

updated_by undefined
Must be one of the below.

Requestee

type string
The actor type (e.g. user, product_module, system).

id string
The unique identifier of the actor.

owner_id string
The organization the actor belongs to.

user_group_id string
The user group the actor is scoped to, where applicable.

executed_at string,null
When execution started. Null until the instruction runs.

executed_by undefined
Must be one of the below.

Requestee

type string
The actor type (e.g. user, product_module, system).

id string
The unique identifier of the actor.

owner_id string
The organization the actor belongs to.

user_group_id string
The user group the actor is scoped to, where applicable.

cancelled_at string,null
When the instruction was cancelled. Null unless cancelled.

cancelled_by undefined
Must be one of the below.

Requestee

type string
The actor type (e.g. user, product_module, system).

id string
The unique identifier of the actor.

owner_id string
The organization the actor belongs to.

user_group_id string
The user group the actor is scoped to, where applicable.

queued_at string,null
When the instruction transitioned to queued. Null if it never queued (e.g. a manually triggered instruction goes straight to executed, and a stale-pending sweep goes straight to failed).

successful_at string,null
When the instruction transitioned to successful. Null otherwise.

failed_at string,null
When the instruction transitioned to failed. Null otherwise.

failure_reason string,null
Populated when status is failed and the failure was caused by a platform-detected condition (a sweep or a missing function). Null for other function-level errors, where the error is recorded in the product module run log instead.

stale — execution_datetime was more than 24 hours in the
past when the cron ran. The platform refused to dispatch the
stale instruction and marked it failed.
stuck_in_queued — instruction sat in queued state for
more than 30 minutes since the last dispatch attempt without
progressing (likely SQS message loss, or retries exhausted to
the dead-letter queue). The sweeper marked it failed;
re-execution requires creating a fresh instruction.
stuck_in_executed — instruction sat in executed state for
more than 30 minutes without reaching a terminal status. The
worker began execution but died before recording
successful/failed. The sweeper marked it failed;
re-execution requires creating a fresh instruction.
function_not_found — the cron/queue invoked the named
function_name but it was not defined on the product
module's published code. Misconfiguration. A platform-emitted
log entry "Function <name> is not defined in this product
module" is written to the product module run log so PM
authors see it in the workbench logs UI.

Note: transient infrastructure / invocation failures (Lambda SDK error, execution service 5xx, network timeout) are NOT recorded as a terminal failure_reason. The instruction is reverted to queued and retried via the SQS redelivery path; if redeliveries are exhausted, the sweep marks it failed with stuck_in_queued.

product_module_code_run_id string,null
UUID of the product_module_code_runs row that recorded this instruction's execution. Populated for executed/successful/failed rows; null for pending/queued/cancelled rows. Use it to deep-link to the full execution log at /product-modules/{product_module_id}/runs/{product_module_code_run_id}/log-items for inspecting any logs the function emitted (including the actual error message for function-thrown failures).

Example

{
  "instruction_id": "4f6a2b8c-d3e1-4f5a-9b8c-1a2b3c4d5e6f",
  "organization_id": "8a7b6c5d-4e3f-2d1c-0b9a-8a7b6c5d4e3f",
  "module_id": "aa11bb22-cc33-dd44-ee55-ff6677889900",
  "module_type": "product_module",
  "policy_id": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
  "claim_id": null,
  "execution_datetime": "2026-06-01T14:00:00.000Z",
  "status": "pending",
  "module": {
    "benefit_key": "home_contents_theft",
    "benefit_start_date": "2025-06-01"
  },
  "function_name": "reset_benefit_home_contents_theft",
  "description": "Reset the home contents theft benefit on its anniversary",
  "environment": "sandbox",
  "hidden": false,
  "manually_executable": true,
  "created_at": "2026-05-12T09:30:00.000Z",
  "created_by": {
    "type": "product_module",
    "id": "aa11bb22-cc33-dd44-ee55-ff6677889900",
    "owner_id": "8a7b6c5d-4e3f-2d1c-0b9a-8a7b6c5d4e3f"
  },
  "updated_at": "2026-05-12T09:30:00.000Z",
  "updated_by": null,
  "executed_at": null,
  "executed_by": null,
  "cancelled_at": null,
  "cancelled_by": null,
  "queued_at": null,
  "successful_at": null,
  "failed_at": null,
  "failure_reason": null,
  "product_module_code_run_id": null
}