Executions and audit
Every call an agent makes becomes an execution: one record of what was asked, what was decided and what happened. Every step of it also goes into an audit trail that can't be edited without it showing.
Execution statuses
| Status | What it means | Final? |
|---|---|---|
| Waiting for approval | Waiting for a person to approve it. | No |
| Approved | Approved. The Gateway is getting permission to run it. | No |
| Sending | Sent to your system. Waiting for its answer. | No |
| Succeeded | Your system did it. | Yes |
| Failed | It didn't happen: your system refused it, couldn't be reached, or the final check before running refused it. | Yes |
| Denied | Refused before anything was sent: by your policy, a limit, a kill switch or invalid input. | Yes |
| Rejected | A person rejected it, the approval request was refused, or Gatelion cancelled it because something changed before it could run. Never sent. | Yes |
| Expired | Nobody approved it in time. Never sent. | Yes |
| Unknown: reconcile | A write was sent, but no reliable answer came back. It may or may not have happened. | Until a person settles it |
The agent sees the same statuses, except that it sees approved while the call is being sent. Each execution also carries a code that says why it ended as it did, for example policy_denied, approval_rejected, or policy_changed for a request cancelled because the policy changed. See Error codes.
When the outcome is unknown
Gatelion never sends a write twice on its own. If it isn't sure whether a write happened, it doesn't guess and doesn't retry. It marks the execution Unknown: reconcile and leaves the decision to a person.
A write ends unknown when it was sent and then:
- the answer took longer than the tool's time limit, or the connection dropped (
no_reliable_response) - your system answered with a server error (
server_error_500,server_error_503and so on) - your system answered with a redirect, which the Gateway doesn't follow (
redirected) - the answer was too large (
response_too_large), or reported success without readable JSON (unreadable_success_response) - the Gateway stopped or restarted while the call was being sent (
interrupted)
Reads in the same situations end failed, because a read changes nothing. A write that never left the Gateway is a definite failure too: for example, when your system's address couldn't be reached at all (unreachable), or the Gateway couldn't sign in to it.
How to reconcile
The console marks these executions "Unknown: reconcile" under Executions & audit. Gatelion can't find out by itself, because only your system knows. A person checks the system, then records what they found in the console.
- Find the execution. Filter Executions & audit by needs settling, which lists the unknown executions nobody has settled yet, and open one. The timeline shows the tool, the agent, the person and the time it was sent.
- Look in your system. Search for the record the call would have created or changed, for example the purchase order, at that time and with those values. If your API supports idempotency keys, search for the execution's key.
- Settle it. Click Settle, choose It happened or It didn't happen, and say under How you know what you found, for example the order number. Admins and the environment's approvers can settle; auditors can't.
- Act on what you found. If the write happened, tell the person who asked. If it didn't, the agent can make the call again. A new call is a new execution, checked and approved like any other.
The execution then shows Settled: it happened or Settled: it didn't happen, with who settled it, when and their note, and its timeline gets Settled by a person. The settlement goes into the audit trail. An execution can be settled once.
Settling doesn't change what the agent sees: get_execution_status still answers unknown. So a well-built agent tells its user to check rather than trying again by itself, and the person who settled the execution tells the user what they found. See Executions and audit for the steps in the console.
Idempotency keys
Each execution has its own idempotency key: gatelion- followed by the execution id as 32 hexadecimal characters, without dashes. If an operation's API description declares an Idempotency-Key header, the Gateway sends this key with the write. An API that stores the key can then tell you whether it already processed that request. See OpenAPI extensions.
The audit trail
The Control Plane records every step as an audit event:
- every call and its outcome, including denied calls and their reasons
- approval requests, each time someone opens one, decisions with their comments, expiries, cancellations, and the final check before running
- settlements of unknown outcomes, with who settled them and their note
- configuration changes: policy versions, tools, connections, agents and whom they may act for, tokens issued and revoked, Gateways switched on or off or retired, and environment settings
- people: invitations, role changes, access removed or restored, sign-ins, and changes to passwords and second factors
An event names who acted (a person, an agent, a Gateway or Gatelion itself), when, for whom, and the argument fingerprint. It doesn't contain the argument values themselves.
In Executions & audit, select an execution to see its timeline, for example: "Agent asked; waiting for a person", "Approved", "Re-checked and released for execution", "Sent to the system", "Completed".
Checking the chain
Each environment's events form a chain. Every event carries a SHA-256 hash of its own content and of the event before it. Changing, deleting or reordering any event breaks the chain from that point on. The database also lets Gatelion's application add and read events, never change or remove them.
The top of Executions & audit shows the result of checking the whole chain each time the page opens:
- Audit chain intact · 1,234 events: every link checks out.
- Audit chain broken at event 512: something changed at that point. Contact Gatelion.
Admins and the environment's auditors see the chain check. Approvers see executions and timelines, but not the check.
Related: Executions and audit for working with the page, and Approvals.
Still stuck? Contact support from the console.