# Events

Launch stage: GA

`GET /api/2.0/pipelines/{pipeline_id}/events`

Retrieves events for a pipeline.

API scopes: pipelines

## Path parameters

- `pipeline_id` (string, optional)
  The pipeline to return events for.

## Query parameters

- `page_token` (string, optional)
  Page token returned by previous call. This field is mutually
   exclusive with all fields in this request except max_results. An error is
   returned if any fields other than max_results are set when this field is set.
- `max_results` (int32, optional)
  Max number of entries to return in a single page. The system may return
   fewer than max_results events in a response, even if there are more events
   available.
  Constraints: `<= 1000`
- `order_by` (array of string, optional)
  A string indicating a sort order by timestamp for the results, for example, ["timestamp asc"].
   The sort order can be ascending or descending. By default, events are returned
   in descending order by timestamp.
- `filter` (string, optional)
  Criteria to select a subset of results, expressed using a SQL-like syntax.
   The supported filters are:
   1. level='INFO' (or WARN or ERROR)
   2. level in ('INFO', 'WARN')
   3. id='[event-id]'
   4. timestamp > 'TIMESTAMP' (or >=,<,<=,=)
  
   Composite expressions are supported, for example: level in ('ERROR', 'WARN')
   AND timestamp> '2021-07-22T06:37:33.083Z'

## Returns

- `events` (array of object, optional)
  The list of events matching the request criteria.
  - `id` (string, optional)
    A time-based, globally unique id.
  - `sequence` (object, optional)
    A sequencing object to identify and order events.
    - `data_plane_id` (object, optional)
      the ID assigned by the data plane.
      - `instance` (string, optional)
        The instance name of the data plane emitting an event.
      - `seq_no` (int64, optional)
        A sequence number, unique and increasing within the data plane instance.
    - `control_plane_seq_no` (int64, optional)
      A sequence number, unique and increasing per pipeline.
  - `origin` (object, optional)
    Describes where the event originates from.
    - `cloud` (string, optional)
      The cloud provider, e.g., AWS or Azure.
    - `region` (string, optional)
      The cloud region.
    - `org_id` (int64, optional)
      The org id of the user. Unique within a cloud.
    - `pipeline_id` (string, optional)
      The id of the pipeline. Globally unique.
    - `pipeline_name` (string, optional)
      The name of the pipeline. Not unique.
    - `cluster_id` (string, optional)
      The id of the cluster where an execution happens. Unique within a region.
    - `update_id` (string, optional)
      The id of an execution. Globally unique.
    - `maintenance_id` (string, optional)
      The id of a maintenance run. Globally unique.
    - `table_id` (string, optional)
      The id of a (delta) table. Globally unique.
    - `dataset_name` (string, optional)
      The name of a dataset. Unique within a pipeline.
    - `flow_id` (string, optional)
      The id of the flow. Globally unique. Incremental queries will generally
       reuse the same id while complete queries will have a new id per update.
    - `flow_name` (string, optional)
      The name of the flow. Not unique.
    - `batch_id` (int64, optional)
      The id of a batch. Unique within a flow.
    - `request_id` (string, optional)
      The id of the request that caused an update.
    - `uc_resource_id` (string, optional)
      The Unity Catalog id of the MV or ST being updated.
    - `host` (string, optional)
      The optional host name where the event was triggered
    - `materialization_name` (string, optional)
      Materialization name.
    - `ingestion_source_connection_name` (string, optional, Public Preview)
      The name of the source UC connection (if known) from whose data ingestion is described by this event.
    - `ingestion_source_catalog_name` (string, optional, Public Preview)
      The name of the source catalog name (if known) from whose data ingestion is described by this event.
    - `ingestion_source_schema_name` (string, optional, Public Preview)
      The name of the source schema name (if known) from whose data ingestion is described by this event.
    - `ingestion_source_table_name` (string, optional, Public Preview)
      The name of the source table name (if known) from whose data ingestion is described by this event.
    - `ingestion_source_table_version` (string, optional, Public Preview)
      An optional implementation-defined source table version of a dataset being (re)ingested.
  - `timestamp` (string, optional)
    The time of the event.
  - `message` (string, optional)
    The display message associated with the event.
  - `level` (string, optional)
    The severity level of the event.
    Possible values: `INFO`, `WARN`, `ERROR`, `METRICS`
  - `error` (object, optional)
    Information about an error captured by the event.
    - `exceptions` (array of object, optional)
      The exception thrown for this error, with its chain of cause.
      - `class_name` (string, optional)
        Runtime class of the exception
      - `message` (string, optional)
        Exception message
      - `stack` (array of object, optional)
        Stack trace consisting of a list of stack frames
    - `fatal` (boolean, optional)
      Whether this error is considered fatal, that is, unrecoverable.
  - `event_type` (string, optional)
    The event type. Should always correspond to the details
  - `maturity_level` (string, optional)
    Maturity level for event_type.
    Possible values: `STABLE`, `EVOLVING`, `DEPRECATED`
  - `truncation` (object, optional)
    Information about which fields were truncated from this event due to size constraints.
     If empty or absent, no truncation occurred.
     See https://docs.databricks.com/en/ldp/monitor-event-logs for information on
     retrieving complete event data.
    - `truncated_fields` (array of object, optional)
      List of fields that were truncated from this event. If empty or absent,
       no truncation occurred.
      - `field_name` (string, optional)
        The name of the truncated field (e.g., "error").
         Corresponds to field names in PipelineEvent.
- `next_page_token` (string, optional)
  If present, a token to fetch the next page of events.
- `prev_page_token` (string, optional)
  If present, a token to fetch the previous page of events.

## Response

```json
{
  "events": [
    {
      "id": "string",
      "sequence": {},
      "origin": {},
      "timestamp": "string",
      "message": "string",
      "level": "string",
      "error": {},
      "event_type": "string",
      "maturity_level": "string",
      "truncation": {}
    }
  ],
  "next_page_token": "string",
  "prev_page_token": "string"
}
```