Jump to

• Request
• Response

List Event Subscriptions

get

/v1/besu/event-subscriptions

Generates a list of all the events subscribed to by the authenticated caller, with optional event type and lifecycle status filtering.

Request

Query Parameters

• status: string
  Optional lifecycle status filter. Matching is case-insensitive.

  Allowed Values: [ "running", "stopped", "deleted", "completed", "expired" ]
• type: string
  Optional event type filter. Matching is case-insensitive.

  Allowed Values: [ "newHeads", "logs" ]

There's no request body for this operation.

Back to Top

Response

Supported Media Types

• application/json

200 Response

Returns the event subscriptions available to the authenticated caller.

Body ()

Root Schema : ListEventSubscriptionsResponse

Type: object

Collection of event subscriptions visible to the authenticated caller.

Show Source

• items: array items
  Collection of subscriptions visible to the authenticated caller.

{
    "type":"object",
    "description":"Collection of event subscriptions visible to the authenticated caller.",
    "properties":{
        "items":{
            "type":"array",
            "description":"Collection of subscriptions visible to the authenticated caller.",
            "items":{
                "$ref":"#/components/schemas/EventSubscriptionResponse"
            }
        }
    }
}

Nested Schema : items

Type: array

Collection of subscriptions visible to the authenticated caller.

Show Source

• Array of: object EventSubscriptionResponse
  Event subscription configuration and current lifecycle state.

{
    "type":"array",
    "description":"Collection of subscriptions visible to the authenticated caller.",
    "items":{
        "$ref":"#/components/schemas/EventSubscriptionResponse"
    }
}

Nested Schema : EventSubscriptionResponse

Type: object

Event subscription configuration and current lifecycle state.

Show Source

• callbackUrl: string
  HTTPS endpoint receiving callback deliveries.
• confirmations: integer
  Block confirmation threshold configured for the subscription.
• cursor: object EventSubscriptionCursor
  Event processing position for an event subscription.
• endBlock: integer (int64)
  Final block number to process before stopping, when provided.
• expiresAt: string (date-time)
  Timestamp after which the subscription is automatically considered expired.
• nonEmptyBlocksOnly: boolean
  Indicates whether empty newHeads blocks are suppressed for this subscription.
• startBlock: integer (int64)
  First block number considered when replaying events, when provided.
• stateChangedAt: string (date-time)
  Timestamp when the lifecycle status was most recently updated.
• stateReason: string
  Optional transition reason for terminal state changes.
• status: string
  Current lifecycle state of the subscription (running, stopped, deleted, completed, or expired).
• subId: string
  Unique identifier for the subscription.
• type: string
  Event type for the subscription (newHeads or logs).

{
    "type":"object",
    "description":"Event subscription configuration and current lifecycle state.",
    "properties":{
        "subId":{
            "type":"string",
            "description":"Unique identifier for the subscription."
        },
        "type":{
            "type":"string",
            "description":"Event type for the subscription (<code>newHeads</code> or <code>logs</code>)."
        },
        "status":{
            "type":"string",
            "description":"Current lifecycle state of the subscription (<code>running</code>, <code>stopped</code>, <code>deleted</code>, <code>completed</code>, or <code>expired</code>)."
        },
        "stateReason":{
            "type":"string",
            "description":"Optional transition reason for terminal state changes."
        },
        "stateChangedAt":{
            "type":"string",
            "format":"date-time",
            "description":"Timestamp when the lifecycle status was most recently updated."
        },
        "callbackUrl":{
            "type":"string",
            "description":"HTTPS endpoint receiving callback deliveries."
        },
        "confirmations":{
            "type":"integer",
            "description":"Block confirmation threshold configured for the subscription."
        },
        "nonEmptyBlocksOnly":{
            "type":"boolean",
            "description":"Indicates whether empty <code>newHeads</code> blocks are suppressed for this subscription."
        },
        "startBlock":{
            "type":"integer",
            "format":"int64",
            "description":"First block number considered when replaying events, when provided."
        },
        "endBlock":{
            "type":"integer",
            "format":"int64",
            "description":"Final block number to process before stopping, when provided."
        },
        "expiresAt":{
            "type":"string",
            "format":"date-time",
            "description":"Timestamp after which the subscription is automatically considered expired."
        },
        "cursor":{
            "$ref":"#/components/schemas/EventSubscriptionCursor"
        }
    }
}

Nested Schema : EventSubscriptionCursor

Type: object

Event processing position for an event subscription.

Show Source

• lastFinalizedBlock: integer (int64)
  Most recent finalized block used for head progression.
• lastFinalizedBlockHash: string
  Block hash for lastFinalizedBlock, when known.
• lastLogBlock: integer (int64)
  Most recent block used for log delivery.
• lastLogBlockHash: string
  Block hash for lastLogBlock, when known.
• lastLogIndex: integer
  Last delivered log index in lastLogBlock when resuming within-block.
• lastLogTxIndex: integer
  Last delivered transaction index in lastLogBlock when resuming within-block.

{
    "type":"object",
    "description":"Event processing position for an event subscription.",
    "properties":{
        "lastFinalizedBlock":{
            "type":"integer",
            "format":"int64",
            "description":"Most recent finalized block used for head progression."
        },
        "lastFinalizedBlockHash":{
            "type":"string",
            "description":"Block hash for <code>lastFinalizedBlock</code>, when known."
        },
        "lastLogBlock":{
            "type":"integer",
            "format":"int64",
            "description":"Most recent block used for log delivery."
        },
        "lastLogBlockHash":{
            "type":"string",
            "description":"Block hash for <code>lastLogBlock</code>, when known."
        },
        "lastLogTxIndex":{
            "type":"integer",
            "description":"Last delivered transaction index in <code>lastLogBlock</code> when resuming within-block."
        },
        "lastLogIndex":{
            "type":"integer",
            "description":"Last delivered log index in <code>lastLogBlock<code> when resuming within-block."
        }
    }
}

Examples

Select an example response_200_subscription_list

400 Response

Validation failed.

Body ()

Root Schema : ErrorResponse

Type: object

Error response returned by the service.

Show Source

• decodedError:
  Returned only when `decode.errors=true` and decodable revert bytes are present.
• error: string
  Short error summary suitable for display.
• hint: [ "string", "null" ]
  Optional guidance for resolving the error.
• message: [ "string", "null" ]
  Additional error details, when available.
• policy:
  Present for policy warnings or denials such as preflight failure.
• preflight:
  Present for preflight-gated transaction submission errors.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed in the response.
• upstreamCode: [ "integer", "null" ]
  Besu node error code, when provided by the RPC endpoint.
• upstreamData: [ "string", "null" ]
  Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete error object returned by the Besu node, including code, message, and data fields, when available.

{
    "type":"object",
    "description":"Error response returned by the service.",
    "properties":{
        "error":{
            "type":"string",
            "description":"Short error summary suitable for display."
        },
        "message":{
            "type":[
                "string",
                "null"
            ],
            "description":"Additional error details, when available."
        },
        "hint":{
            "type":[
                "string",
                "null"
            ],
            "description":"Optional guidance for resolving the error."
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu node error code, when provided by the RPC endpoint."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
        },
        "preflight":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPreflightResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for preflight-gated transaction submission errors."
        },
        "policy":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPolicyDecision"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for policy warnings or denials such as preflight failure."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed in the response."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete error object returned by the Besu node, including code, message, and data fields, when available.

Examples

Select an example response_400_list_filter_validation_error

500 Response

Unexpected service error.

Body ()

Root Schema : ErrorResponse

Type: object

Error response returned by the service.

Show Source

• decodedError:
  Returned only when `decode.errors=true` and decodable revert bytes are present.
• error: string
  Short error summary suitable for display.
• hint: [ "string", "null" ]
  Optional guidance for resolving the error.
• message: [ "string", "null" ]
  Additional error details, when available.
• policy:
  Present for policy warnings or denials such as preflight failure.
• preflight:
  Present for preflight-gated transaction submission errors.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed in the response.
• upstreamCode: [ "integer", "null" ]
  Besu node error code, when provided by the RPC endpoint.
• upstreamData: [ "string", "null" ]
  Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete error object returned by the Besu node, including code, message, and data fields, when available.

{
    "type":"object",
    "description":"Error response returned by the service.",
    "properties":{
        "error":{
            "type":"string",
            "description":"Short error summary suitable for display."
        },
        "message":{
            "type":[
                "string",
                "null"
            ],
            "description":"Additional error details, when available."
        },
        "hint":{
            "type":[
                "string",
                "null"
            ],
            "description":"Optional guidance for resolving the error."
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu node error code, when provided by the RPC endpoint."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
        },
        "preflight":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPreflightResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for preflight-gated transaction submission errors."
        },
        "policy":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPolicyDecision"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for policy warnings or denials such as preflight failure."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed in the response."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete error object returned by the Besu node, including code, message, and data fields, when available.

Examples

Select an example response_500_internal_error

503 Response

Event subscriptions are unavailable.

Body ()

Root Schema : ErrorResponse

Type: object

Error response returned by the service.

Show Source

• decodedError:
  Returned only when `decode.errors=true` and decodable revert bytes are present.
• error: string
  Short error summary suitable for display.
• hint: [ "string", "null" ]
  Optional guidance for resolving the error.
• message: [ "string", "null" ]
  Additional error details, when available.
• policy:
  Present for policy warnings or denials such as preflight failure.
• preflight:
  Present for preflight-gated transaction submission errors.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed in the response.
• upstreamCode: [ "integer", "null" ]
  Besu node error code, when provided by the RPC endpoint.
• upstreamData: [ "string", "null" ]
  Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete error object returned by the Besu node, including code, message, and data fields, when available.

{
    "type":"object",
    "description":"Error response returned by the service.",
    "properties":{
        "error":{
            "type":"string",
            "description":"Short error summary suitable for display."
        },
        "message":{
            "type":[
                "string",
                "null"
            ],
            "description":"Additional error details, when available."
        },
        "hint":{
            "type":[
                "string",
                "null"
            ],
            "description":"Optional guidance for resolving the error."
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu node error code, when provided by the RPC endpoint."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
        },
        "preflight":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPreflightResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for preflight-gated transaction submission errors."
        },
        "policy":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPolicyDecision"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for policy warnings or denials such as preflight failure."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed in the response."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete error object returned by the Besu node, including code, message, and data fields, when available.

Examples

Select an example response_503_feature_disabled

Back to Top