# List events

> List lifecycle events recorded with or without webhooks. Events and their deliveries expire according to the plan retention deadline. Historical notifications recorded before the event log remain available through Notifications.

```json
{
  "path": "/events",
  "method": "get",
  "schema": {
    "description": "List lifecycle events recorded with or without webhooks. Events and their deliveries expire according to the plan retention deadline. Historical notifications recorded before the event log remain available through Notifications.",
    "operationId": "listEvents",
    "parameters": [
      {
        "description": "Filter by the primary or a related resource ID, including retained associations after resource deletion.",
        "in": "query",
        "name": "object_id",
        "schema": {
          "type": "string"
        }
      },
      {
        "description": "Filter by events",
        "in": "query",
        "name": "events",
        "schema": {
          "items": {
            "$ref": "#/components/schemas/WebhookEvent"
          },
          "type": "array"
        }
      },
      {
        "description": "Pagination offset",
        "in": "query",
        "name": "offset",
        "schema": {
          "default": 0,
          "minimum": 0,
          "type": "integer"
        }
      },
      {
        "description": "Pagination limit (max 100)",
        "in": "query",
        "name": "limit",
        "schema": {
          "default": 100,
          "maximum": 100,
          "minimum": 1,
          "type": "integer"
        }
      },
      {
        "description": "Filter by creation date greater than or equal (UNIX epoch time)",
        "in": "query",
        "name": "created.gte",
        "schema": {
          "examples": [
            "1764238404"
          ],
          "format": "epoch",
          "minimum": 0,
          "type": "integer"
        }
      },
      {
        "description": "Filter by creation date less than or equal (UNIX epoch time)",
        "in": "query",
        "name": "created.lte",
        "schema": {
          "examples": [
            "1764238404"
          ],
          "format": "epoch",
          "minimum": 0,
          "type": "integer"
        }
      },
      {
        "description": "Sort by creation date (asc/desc)",
        "in": "query",
        "name": "created.sort",
        "schema": {
          "default": "desc",
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        }
      }
    ],
    "responses": {
      "200": {
        "content": {
          "application/json": {
            "example": {
              "data": [
                {
                  "created_at": "2026-09-18T08:00:00Z",
                  "delivery_count": 0,
                  "delivery_status": "none",
                  "event": "upload.expired",
                  "expires_at": "2026-09-25T08:00:00Z",
                  "id": "evt_example",
                  "object_id": "upl_example",
                  "payload": "{\"id\":\"evt_example\",\"event\":\"upload.expired\",\"date\":\"2026-09-18T08:00:00Z\",\"data\":{\"upload\":{\"id\":\"upl_example\",\"status\":\"expired\"}}}",
                  "related_object_ids": [
                    "upl_example"
                  ]
                }
              ],
              "limit": 100,
              "offset": 0,
              "status": "success",
              "total": 1
            },
            "schema": {
              "$ref": "#/components/schemas/EventListResponse"
            }
          }
        },
        "description": "OK"
      },
      "400": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorValidation"
            }
          }
        },
        "description": "Invalid filters."
      },
      "401": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorAuthentication"
            }
          }
        },
        "description": "Authentication error: invalid token or subscription inactive"
      },
      "429": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorTooManyRequests"
            }
          }
        },
        "description": "Rate limit exceeded"
      }
    },
    "security": [
      {
        "ProjectAccessToken": []
      }
    ],
    "summary": "List events",
    "tags": [
      "Events"
    ],
    "x-codeSamples": [
      {
        "lang": "JavaScript",
        "source": "import Chunkify from '@chunkify/chunkify';\n\nconst client = new Chunkify({\n  projectAccessToken: 'My Project Access Token',\n});\n\n// Automatically fetches more pages as needed.\nfor await (const event of client.events.list()) {\n  console.log(event.id);\n}"
      },
      {
        "lang": "Python",
        "source": "from chunkify import Chunkify\n\nclient = Chunkify(\n    project_access_token=\"My Project Access Token\",\n)\n\n# Automatically fetches more pages as needed.\nfor event in client.events.list():\n   print(event.id)"
      },
      {
        "lang": "php",
        "source": "\u003c?php\n\nuse Chunkify\\Client;\n\n$client = new Client(\n    projectAccessToken: 'My Project Access Token',\n);\n\n// Automatically fetches more pages as needed.\nforeach ($client-\u003eevents-\u003elist()-\u003epagingEachItem() as $event) {\n    var_dump($event-\u003eid);\n}"
      },
      {
        "lang": "Go",
        "source": "package main\n\nimport (\n  \"context\"\n  \"fmt\"\n\n  \"github.com/chunkifydev/chunkify-go\"\n  \"github.com/chunkifydev/chunkify-go/option\"\n)\n\nfunc main() {\n  client := chunkify.NewClient(\n    option.WithProjectAccessToken(\"My Project Access Token\"),\n  )\n  page, err := client.Events.List(\n    context.TODO(),\n    chunkify.EventListParams{},\n  )\n  if err != nil {\n    panic(err.Error())\n  }\n\n  // Loop through the pages and print the events IDs\n  for page != nil {\n    for _, event := range page.Data {\n      fmt.Printf(\"%+v\\n\", event.ID)\n    }\n    page, err = page.GetNextPage()\n    if err != nil {\n      panic(err.Error())\n    }\n  }\n}\n"
      }
    ]
  }
}
```



```json #/components/schemas/WebhookEvent
{
  "enum": [
    "job.created",
    "job.completed",
    "job.failed",
    "job.cancelled",
    "source.created",
    "source.deleted",
    "upload.created",
    "upload.completed",
    "upload.failed",
    "upload.expired",
    "asset.created",
    "asset.ready",
    "asset.playback_ready",
    "asset.failed",
    "asset.expired",
    "asset.deleted",
    "asset.output.created",
    "asset.output.ready",
    "asset.output.failed",
    "asset.output.deleted",
    "workflow_run.created",
    "workflow_run.completed",
    "workflow_run.failed",
    "workflow_run.cancelled",
    "transcoding.created",
    "transcoding.ready",
    "transcoding.failed",
    "transcoding.cancelled",
    "transcoding.expired",
    "transcoding.deleted",
    "thumbnail.created",
    "thumbnail.ready",
    "thumbnail.failed",
    "thumbnail.expired",
    "thumbnail.deleted"
  ],
  "examples": [
    "asset.playback_ready"
  ],
  "type": "string"
}
```



```json #/components/schemas/EventListResponse
{
  "description": "Paginated retained lifecycle events.",
  "properties": {
    "data": {
      "description": "Events ordered by occurrence time and ID.",
      "items": {
        "$ref": "#/components/schemas/Event"
      },
      "type": "array"
    },
    "limit": {
      "description": "Limit indicates the maximum number of items in the current response",
      "type": "integer"
    },
    "offset": {
      "description": "Offset indicates the offset of the first item in the current response",
      "type": "integer"
    },
    "status": {
      "const": "success",
      "description": "Status indicates the response status \"success\"",
      "type": "string"
    },
    "total": {
      "description": "Total indicates the total number of items",
      "type": "integer"
    }
  },
  "required": [
    "data",
    "limit",
    "offset",
    "status",
    "total"
  ],
  "type": "object"
}
```



```json #/components/schemas/Event
{
  "description": "A retained lifecycle event, recorded independently of webhook subscriptions. The payload is an immutable JSON snapshot.",
  "properties": {
    "created_at": {
      "description": "Time the event occurred.",
      "format": "date-time",
      "type": "string"
    },
    "deliveries": {
      "description": "First 100 delivery attempts, oldest first; included on retrieval. List notifications with event_id to paginate all attempts.",
      "items": {
        "$ref": "#/components/schemas/Notification"
      },
      "type": "array"
    },
    "delivery_count": {
      "description": "Number of retained webhook delivery attempts.",
      "type": "integer"
    },
    "delivery_status": {
      "description": "Summary of the latest retained attempt for each webhook. none means no retained attempts; pending means at least one latest attempt is awaiting delivery; failed means at least one latest attempt failed and none are pending; delivered means all latest attempts succeeded. Earlier failures superseded by successful retries do not mark the event failed.",
      "enum": [
        "none",
        "pending",
        "delivered",
        "failed"
      ],
      "type": "string"
    },
    "event": {
      "$ref": "#/components/schemas/WebhookEvent"
    },
    "expires_at": {
      "description": "Retention deadline set from the project team plan when the event was recorded. Deliveries and retries share this deadline.",
      "format": "date-time",
      "type": "string"
    },
    "id": {
      "description": "Unique event ID.",
      "examples": [
        "evt_2G6MJiNz71bHQGNzGwKx5cJwPFS"
      ],
      "type": "string"
    },
    "object_id": {
      "description": "ID of the resource that caused this event.",
      "type": "string"
    },
    "payload": {
      "description": "Immutable JSON event envelope. Its ID is the event ID; webhook delivery envelopes retain their notification IDs. Signed links in historical snapshots may have expired.",
      "type": "string"
    },
    "related_object_ids": {
      "description": "Related resource IDs retained independently of resource deletion.",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "id",
    "object_id",
    "event",
    "created_at",
    "expires_at",
    "payload",
    "related_object_ids",
    "delivery_count",
    "delivery_status"
  ],
  "type": "object"
}
```



```json #/components/schemas/Notification
{
  "properties": {
    "created_at": {
      "description": "Timestamp when the notification was created",
      "examples": [
        "2025-01-01T12:00:00Z"
      ],
      "format": "date-time",
      "type": "string"
    },
    "event": {
      "$ref": "#/components/schemas/WebhookEvent",
      "description": "Type of event that triggered this notification"
    },
    "event_id": {
      "description": "Originating event ID, when recorded by the event log.",
      "type": "string"
    },
    "id": {
      "description": "Unique identifier of the notification",
      "examples": [
        "notf_2G6MJiNz71bHQGNzGwKx5cJwPFS"
      ],
      "type": "string"
    },
    "object_id": {
      "description": "ID of the object that triggered this notification",
      "examples": [
        "ast_2G6MJiNz71bHQGNzGwKx5cJwPFS"
      ],
      "type": "string"
    },
    "payload": {
      "description": "JSON payload that was sent to the webhook endpoint",
      "examples": [
        "{\"id\":\"notf_2G6MJiNz71bHQGNzGwKx5cJwPFS\",\"event\":\"asset.playback_ready\",\"date\":\"2025-01-01T12:00:00Z\",\"data\":{\"asset\":{\"id\":\"ast_2G6MJiNz71bHQGNzGwKx5cJwPFS\",\"status\":\"preparing\",\"playback_ready\":true}}}"
      ],
      "type": "string"
    },
    "response_status_code": {
      "description": "HTTP status code received from the webhook endpoint",
      "examples": [
        200
      ],
      "type": "integer"
    },
    "webhook": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Webhook"
        }
      ],
      "description": "Webhook endpoint configuration that received this notification"
    }
  },
  "required": [
    "created_at",
    "event",
    "id",
    "object_id",
    "payload",
    "webhook"
  ],
  "type": "object"
}
```



```json #/components/schemas/WebhookEvent
{
  "enum": [
    "job.created",
    "job.completed",
    "job.failed",
    "job.cancelled",
    "source.created",
    "source.deleted",
    "upload.created",
    "upload.completed",
    "upload.failed",
    "upload.expired",
    "asset.created",
    "asset.ready",
    "asset.playback_ready",
    "asset.failed",
    "asset.expired",
    "asset.deleted",
    "asset.output.created",
    "asset.output.ready",
    "asset.output.failed",
    "asset.output.deleted",
    "workflow_run.created",
    "workflow_run.completed",
    "workflow_run.failed",
    "workflow_run.cancelled",
    "transcoding.created",
    "transcoding.ready",
    "transcoding.failed",
    "transcoding.cancelled",
    "transcoding.expired",
    "transcoding.deleted",
    "thumbnail.created",
    "thumbnail.ready",
    "thumbnail.failed",
    "thumbnail.expired",
    "thumbnail.deleted"
  ],
  "examples": [
    "asset.playback_ready"
  ],
  "type": "string"
}
```



```json #/components/schemas/Webhook
{
  "properties": {
    "enabled": {
      "description": "Whether the webhook is currently enabled",
      "examples": [
        true
      ],
      "type": "boolean"
    },
    "events": {
      "description": "Array of event types this webhook subscribes to",
      "examples": [
        [
          "asset.playback_ready",
          "asset.failed"
        ]
      ],
      "items": {
        "$ref": "#/components/schemas/WebhookEvent"
      },
      "type": "array"
    },
    "id": {
      "description": "Unique identifier of the webhook",
      "examples": [
        "wh_2G6MJiNz71bHQGNzGwKx5cJwPFS"
      ],
      "type": "string"
    },
    "project_id": {
      "description": "ID of the project this webhook belongs to",
      "examples": [
        "proj_2G6MJiNz71bHQGNzGwKx5cJwPFS"
      ],
      "type": "string"
    },
    "url": {
      "description": "URL where webhook events will be sent",
      "examples": [
        "https://example.com/webhook"
      ],
      "type": "string"
    }
  },
  "required": [
    "enabled",
    "events",
    "id",
    "project_id",
    "url"
  ],
  "type": "object"
}
```



```json #/components/schemas/WebhookEvent
{
  "enum": [
    "job.created",
    "job.completed",
    "job.failed",
    "job.cancelled",
    "source.created",
    "source.deleted",
    "upload.created",
    "upload.completed",
    "upload.failed",
    "upload.expired",
    "asset.created",
    "asset.ready",
    "asset.playback_ready",
    "asset.failed",
    "asset.expired",
    "asset.deleted",
    "asset.output.created",
    "asset.output.ready",
    "asset.output.failed",
    "asset.output.deleted",
    "workflow_run.created",
    "workflow_run.completed",
    "workflow_run.failed",
    "workflow_run.cancelled",
    "transcoding.created",
    "transcoding.ready",
    "transcoding.failed",
    "transcoding.cancelled",
    "transcoding.expired",
    "transcoding.deleted",
    "thumbnail.created",
    "thumbnail.ready",
    "thumbnail.failed",
    "thumbnail.expired",
    "thumbnail.deleted"
  ],
  "examples": [
    "asset.playback_ready"
  ],
  "type": "string"
}
```



```json #/components/schemas/WebhookEvent
{
  "enum": [
    "job.created",
    "job.completed",
    "job.failed",
    "job.cancelled",
    "source.created",
    "source.deleted",
    "upload.created",
    "upload.completed",
    "upload.failed",
    "upload.expired",
    "asset.created",
    "asset.ready",
    "asset.playback_ready",
    "asset.failed",
    "asset.expired",
    "asset.deleted",
    "asset.output.created",
    "asset.output.ready",
    "asset.output.failed",
    "asset.output.deleted",
    "workflow_run.created",
    "workflow_run.completed",
    "workflow_run.failed",
    "workflow_run.cancelled",
    "transcoding.created",
    "transcoding.ready",
    "transcoding.failed",
    "transcoding.cancelled",
    "transcoding.expired",
    "transcoding.deleted",
    "thumbnail.created",
    "thumbnail.ready",
    "thumbnail.failed",
    "thumbnail.expired",
    "thumbnail.deleted"
  ],
  "examples": [
    "asset.playback_ready"
  ],
  "type": "string"
}
```



```json #/components/schemas/ResponseErrorValidation
{
  "properties": {
    "error": {
      "properties": {
        "code": {
          "const": 400,
          "description": "Code is the HTTP status code",
          "examples": [
            400
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "Invalid request parameters"
          ],
          "type": "string"
        },
        "type": {
          "const": "ValidationError",
          "description": "Type indicates the error category",
          "enum": [
            "ValidationError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ]
}
```



```json #/components/schemas/ResponseErrorAuthentication
{
  "description": "Error response",
  "properties": {
    "error": {
      "description": "Error response details",
      "properties": {
        "code": {
          "const": 401,
          "description": "Code is the HTTP status code",
          "examples": [
            401
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "Authentication error: invalid token or subscription inactive"
          ],
          "type": "string"
        },
        "type": {
          "const": "AuthenticationError",
          "description": "Type indicates the error category",
          "enum": [
            "AuthenticationError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ],
  "type": "object"
}
```



```json #/components/schemas/ResponseErrorTooManyRequests
{
  "description": "Error response",
  "properties": {
    "error": {
      "description": "Error response details",
      "properties": {
        "code": {
          "const": 429,
          "description": "Code is the HTTP status code",
          "examples": [
            429
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "Rate limit exceeded"
          ],
          "type": "string"
        },
        "type": {
          "const": "TooManyRequestsError",
          "description": "Type indicates the error category",
          "enum": [
            "TooManyRequestsError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ],
  "type": "object"
}
```