Rules Execution Log

A rules execution log is a record of rule execution. When a rule is triggered and evaluated, the backend logs the trigger event, condition evaluation results, and executed actions.

This endpoint provides visibility into rule execution history for debugging and monitoring purposes.

The retention policy for the logs is set to 7 days.

Rules execution logs response

Attribute

Type

Description

results*

list[object]

List of rule execution log entries.

rule_id*

integer

ID of the rule that was executed.

rule_name*

string

Name of the rule at the time of execution.

queue_id*

integer

ID of the queue where the rule was triggered.

annotation_id*

integer

ID of the annotation that triggered the rule.

request_id*

string

Unique identifier for this rule execution request.

created_at*

datetime

Timestamp when the rule was executed.

trigger_event*

string

Event that triggered the rule evaluation.

trigger_condition*

string

The trigger condition expression that was evaluated.

trigger_condition_results*

array | null

Array of boolean results from trigger condition evaluation.

Regular rules: Array with a single element (e.g., [true]})
Line item rules: One result per line item row (e.g., [false, true, true] for 3 rows where rows 1 and 2 matched)

All arrays (trigger_condition_results, trigger_condition_values, actions) are aligned by index for line item rules.

trigger_condition_values*

array | null

Array of objects containing the field values used in trigger condition evaluation. Keys are schema IDs referenced in the trigger condition.

Regular rules: Array with a single object (e.g., [{"amount_total": "1500.00"}])
Line item rules: One object per line item row, each containing that row's field values (e.g., [{"item_price": "80"}, {"item_price": "150"}, {"item_price": "90"}])

Aligned by index with trigger_condition_results and actions.

execution_result*

"success" | "failure" | "partial_success"

Overall result of the rule execution.

success: All actions executed successfully.
failure: All actions failed to execute.
partial_success: Some actions succeeded while others failed (for line item rules).

execution_error*

string | null

Error message if the rule execution failed.

actions*

array | null

Array of executed actions per trigger condition result. null if all conditions were false.

Regular rules: Array with a single element containing all actions (e.g., [[action1, action2]])
Line item rules: One element per line item row, aligned with trigger_condition_results. Elements are null for rows where the condition was false (e.g., [null, [action], null] for 3 rows where only row 1 matched)

For line item rules, builtin actions (show_message, add_automation_blocker) are replicated for each matching row, while handler actions (send_email, add_label, etc.) are distributed one-to-one to matching rows.

pagination*

object

URL

URL for the next page of results. Contains an opaque signed cursor query parameter. Use this URL directly to fetch the next page — do not attempt to construct or modify the cursor value.

URL

URL for the previous page of results. Contains an opaque signed cursor query parameter. Use this URL directly to fetch the previous page — do not attempt to construct or modify the cursor value.

List rules execution logs

List rules execution logs with optional filters and pagination.

Returns paginated rule execution records (controlled by page_size), including trigger conditions, evaluation results, and executed actions.

curl -X GET "https://example.rossum.app/api/v1/rules_execution_logs?rule=123%2C456&request_id=6166deb3-2f89-4fc2-9359-56cc8e3838e4&execution_result=success&trigger_event=annotation_imported&search=invoice&page_size=50"

curl -X GET "https://example.rossum.app/api/v1/rules_execution_logs?rule=123%2C456&request_id=6166deb3-2f89-4fc2-9359-56cc8e3838e4&execution_result=success&trigger_event=annotation_imported&search=invoice&page_size=50"

{
  "results": [
    {
      "rule_id": 123,
      "rule_name": "Auto-confirm invoices over $1000",
      "queue_id": 456,
      "annotation_id": 789,
      "request_id": "6166deb3-2f89-4fc2-9359-56cc8e3838e4",
      "created_at": "2024-01-15T10:30:00.000000Z",
      "trigger_event": "annotation_imported",
      "trigger_condition": "field.amount_total > 1000",
      "trigger_condition_results": [
        true
      ],
      "trigger_condition_values": [
        {
          "amount_total": "1500.00"
        }
      ],
      "execution_result": "success",
      "execution_error": null,
      "actions": [
        [
          {
            "action_id": "a1",
            "action_type": "send_email",
            "execution_result": "success",
            "execution_error": null,
            "payload": {
              "to": [
                "accountant@example.com"
              ],
              "cc": [
                "manager@example.com"
              ],
              "subject": "Invoice processed",
              "body": "Invoice has been processed successfully.",
              "attach_document": true
            }
          },
          {
            "action_id": "a2",
            "action_type": "add_label",
            "execution_result": "success",
            "execution_error": null,
            "payload": {
              "labels": [
                "https://example.rossum.app/api/v1/labels/123"
              ]
            }
          },
          {
            "action_id": "a3",
            "action_type": "change_status",
            "execution_result": "success",
            "execution_error": null,
            "payload": {
              "method": "postpone"
            }
          }
        ]
      ]
    }
  ],
  "pagination": {
    "next": null,
    "previous": null
  }
}

{
  "detail": "Bad Request.",
  "code": "bad_request"
}

{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}

{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}

{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}

{
  "detail": "Server error.",
  "code": "error"
}

{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}

{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}

{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Response

200OK

Attribute

Type

Description

results*

list[object]

List of rule execution log entries.

rule_id*

integer

ID of the rule that was executed.

rule_name*

string

Name of the rule at the time of execution.

queue_id*

integer

ID of the queue where the rule was triggered.

annotation_id*

integer

ID of the annotation that triggered the rule.

request_id*

string

Unique identifier for this rule execution request.

created_at*

datetime

Timestamp when the rule was executed.

trigger_event*

string

Event that triggered the rule evaluation.

trigger_condition*

string

The trigger condition expression that was evaluated.

trigger_condition_results*

array | null

Array of boolean results from trigger condition evaluation.

Regular rules: Array with a single element (e.g., [true]})
Line item rules: One result per line item row (e.g., [false, true, true] for 3 rows where rows 1 and 2 matched)

All arrays (trigger_condition_results, trigger_condition_values, actions) are aligned by index for line item rules.

trigger_condition_values*

array | null

Array of objects containing the field values used in trigger condition evaluation. Keys are schema IDs referenced in the trigger condition.

Regular rules: Array with a single object (e.g., [{"amount_total": "1500.00"}])
Line item rules: One object per line item row, each containing that row's field values (e.g., [{"item_price": "80"}, {"item_price": "150"}, {"item_price": "90"}])

Aligned by index with trigger_condition_results and actions.

execution_result*

"success" | "failure" | "partial_success"

Overall result of the rule execution.

success: All actions executed successfully.
failure: All actions failed to execute.
partial_success: Some actions succeeded while others failed (for line item rules).

execution_error*

string | null

Error message if the rule execution failed.

actions*

array | null

Array of executed actions per trigger condition result. null if all conditions were false.

Regular rules: Array with a single element containing all actions (e.g., [[action1, action2]])
Line item rules: One element per line item row, aligned with trigger_condition_results. Elements are null for rows where the condition was false (e.g., [null, [action], null] for 3 rows where only row 1 matched)

pagination*

object

URL

URL for the next page of results. Contains an opaque signed cursor query parameter. Use this URL directly to fetch the next page — do not attempt to construct or modify the cursor value.

URL

URL for the previous page of results. Contains an opaque signed cursor query parameter. Use this URL directly to fetch the previous page — do not attempt to construct or modify the cursor value.

400Bad Request

Invalid input data.

Attribute

Type

Description

detail

read-only

string

Detail of the error

code

read-only

string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute

Type

Description

detail

read-only

string

Detail of the error

code

read-only

string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute

Type

Description

detail

read-only

string

Detail of the error

code

read-only

string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute

Type

Description

detail

read-only

string

Detail of the error

code

read-only

string

Code of the error

url

read-only

string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute

Type

Description

detail

read-only

string

Detail of the error

code

read-only

string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute

Type

Description

detail

read-only

string

Detail of the error

code

read-only

string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute

Type

Description

detail

read-only

string

Detail of the error

code

read-only

string

Code of the error

504

Upstream server could not complete the request in time.

Attribute

Type

Description

detail

read-only

string

Detail of the error

code

read-only

string

Code of the error