> ## Documentation Index > Fetch the complete documentation index at: https://docs.oleander.dev/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve events > List lineage events. Supports filtering by time range, run, state, namespace, job, and integrations. Results can be paginated and sorted. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/events openapi: 3.0.1 info: title: Oleander API description: >- Oleander implements the api spec as defined by OpenLineage to ingest data. We also provide a RESTful API to extract data within our system. version: 1.0.0 servers: - url: https://oleander.dev security: - bearerAuth: [] paths: /api/v1/events: get: summary: Retrieve events description: >- List lineage events. Supports filtering by time range, run, state, namespace, job, and integrations. Results can be paginated and sorted. operationId: getLineageEvents parameters: - name: start in: query description: >- Start timestamp (UNIX epoch). Only events with event_time >= this value are returned. required: true schema: type: integer format: int64 example: 1672531200 - name: end in: query description: >- End timestamp (UNIX epoch). Only events with event_time < this value are returned. required: true schema: type: integer format: int64 example: 1672617600 - name: sort_by in: query description: Field by which results should be sorted. Defaults to EVENT_TIME. required: false schema: type: string enum: - EVENT_TIME - EVENT_SIZE_IN_BYTES default: EVENT_TIME - name: order in: query description: Sort order. Defaults to DESC. required: false schema: type: string enum: - ASC - DESC default: DESC - name: run in: query description: >- Filter by run_id (UUID). Only events matching this run_id are returned. required: false schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 - name: states in: query description: >- Comma-separated list of run states to filter by. E.g. 'START,RUNNING,COMPLETE'. required: false schema: type: string enum: - START - RUNNING - COMPLETE - ABORT - FAIL - OTHER - name: namespace in: query description: Filter by job namespace, partial matches included. required: false schema: type: string example: my-scheduler-namespace - name: job in: query description: Filter by job name, partial matches included. required: false schema: type: string example: myjob.mytask - name: integrations in: query description: Comma-separated list of integration names to filter by. required: false schema: type: string example: airflow,dbt - name: limit in: query description: Number of results to return. Defaults to 30. required: false schema: type: integer default: 30 example: 50 - name: offset in: query description: Offset for pagination. Defaults to 0. required: false schema: type: integer default: 0 example: 100 responses: '200': description: A list of lineage events. content: application/json: schema: type: array items: $ref: '#/components/schemas/LineageEvent' '400': description: Invalid request (e.g. parameter validation error). content: application/json: schema: type: object properties: error: type: string example: Validation error details. '401': description: >- Unauthorized – request either lacks a valid Bearer token or session credentials. content: application/json: schema: type: object properties: error: type: string example: Unauthorized '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: LineageEvent: type: object description: Corresponds to the lineageEventSchema in your TypeScript code. properties: id: type: string format: uuid parent_run_id: type: string format: uuid nullable: true description: Optional parent run ID. parent_job_namespace: type: string nullable: true description: Optional parent job namespace. parent_job_name: type: string nullable: true description: Optional parent job name. run_id: type: string format: uuid run_state: type: string enum: - START - RUNNING - COMPLETE - ABORT - FAIL - OTHER received_at: type: string format: date-time description: Timestamp with offset, e.g. '2023-07-14T12:34:56Z'. job_name: type: string job_namespace: type: string inputs: type: array description: List of input datasets. items: type: object properties: namespace: type: string name: type: string nullable: true outputs: type: array description: List of output datasets. items: type: object properties: namespace: type: string name: type: string nullable: true event_time: type: string format: date-time description: Event occurrence time (with offset). event_schema: type: string format: uri event_schema_version: type: string event_size_in_bytes: type: integer description: Size of the raw event payload in bytes. event_raw: $ref: '#/components/schemas/OpenLineageEvent' description: Arbitrary structure corresponding to rawLineageEventSchema. produced_by: type: string format: uri integration: type: string integration_version: type: string required: - id - run_id - run_state - received_at - job_name - job_namespace - event_time - event_schema - event_schema_version - event_size_in_bytes - event_raw - produced_by - integration - integration_version Error: required: - status type: object properties: status: type: integer format: int32 default: 500 OpenLineageEvent: type: object oneOf: - $ref: '#/components/schemas/RunEvent' title: Run Event description: A RunEvent is an event that describes the lifecycle of a run. RunEvent: allOf: - $ref: '#/components/schemas/BaseEvent' - type: object properties: eventType: description: >- the current transition of the run state. It is required to issue 1 START event and 1 of [ COMPLETE, ABORT, FAIL ] event per run. Additional events with OTHER eventType can be added to the same run. For example to send additional metadata after the run is complete type: string enum: - START - RUNNING - COMPLETE - ABORT - FAIL - OTHER example: START|RUNNING|COMPLETE|ABORT|FAIL|OTHER run: $ref: '#/components/schemas/Run' job: $ref: '#/components/schemas/Job' inputs: description: The set of **input** datasets. type: array items: $ref: '#/components/schemas/InputDataset' outputs: description: The set of **output** datasets. type: array items: $ref: '#/components/schemas/OutputDataset' required: - run - job BaseEvent: type: object properties: eventTime: description: the time the event occurred at type: string format: date-time producer: description: >- URI identifying the producer of this metadata. For example this could be a git url with a given tag or sha type: string format: uri example: https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/client schemaURL: description: >- The JSON Pointer (https://tools.ietf.org/html/rfc6901) URL to the corresponding version of the schema definition for this RunEvent type: string format: uri example: https://openlineage.io/spec/0-0-1/OpenLineage.json required: - eventTime - producer - schemaURL Run: type: object properties: runId: description: The globally unique ID of the run associated with the job. type: string format: uuid facets: description: The run facets. type: object anyOf: - type: object additionalProperties: $ref: '#/components/schemas/RunFacet' required: - runId Job: type: object properties: namespace: description: The namespace containing that job type: string example: my-scheduler-namespace name: description: The unique name for that job within that namespace type: string example: myjob.mytask facets: description: The job facets. type: object anyOf: - type: object additionalProperties: $ref: '#/components/schemas/JobFacet' required: - namespace - name InputDataset: description: An input dataset type: object allOf: - $ref: '#/components/schemas/Dataset' - type: object properties: inputFacets: description: The input facets for this dataset. type: object anyOf: - type: object additionalProperties: $ref: '#/components/schemas/InputDatasetFacet' OutputDataset: description: An output dataset type: object allOf: - $ref: '#/components/schemas/Dataset' - type: object properties: outputFacets: description: The output facets for this dataset type: object anyOf: - type: object additionalProperties: $ref: '#/components/schemas/OutputDatasetFacet' RunFacet: description: A Run Facet type: object allOf: - $ref: '#/components/schemas/BaseFacet' JobFacet: description: A Job Facet type: object allOf: - $ref: '#/components/schemas/BaseFacet' - type: object properties: _deleted: description: set to true to delete a facet type: boolean Dataset: type: object properties: namespace: description: The namespace containing that dataset type: string example: my-datasource-namespace name: description: The unique name for that dataset within that namespace type: string example: instance.schema.table facets: description: The facets for this dataset type: object anyOf: - type: object additionalProperties: $ref: '#/components/schemas/DatasetFacet' required: - namespace - name InputDatasetFacet: description: An Input Dataset Facet type: object allOf: - $ref: '#/components/schemas/BaseFacet' OutputDatasetFacet: description: An Output Dataset Facet type: object allOf: - $ref: '#/components/schemas/BaseFacet' BaseFacet: description: >- all fields of the base facet are prefixed with _ to avoid name conflicts in facets type: object properties: _producer: description: >- URI identifying the producer of this metadata. For example this could be a git url with a given tag or sha type: string format: uri example: https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/client _schemaURL: description: >- The JSON Pointer (https://tools.ietf.org/html/rfc6901) URL to the corresponding version of the schema definition for this facet type: string format: uri example: https://openlineage.io/spec/1-0-2/OpenLineage.json#/$defs/BaseFacet additionalProperties: true required: - _producer - _schemaURL DatasetFacet: description: A Dataset Facet type: object allOf: - $ref: '#/components/schemas/BaseFacet' - type: object properties: _deleted: description: set to true to delete a facet type: boolean securitySchemes: bearerAuth: type: http scheme: bearer ````