> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowengineering.com/llms.txt > Use this file to discover all available pages before exploring further. # Read the project event stream > Engineering events for one project in delivery order: branch.changed (item changes on a branch or Base, one event per branch and actor within the page, with the touched entity ids and the origin diff-seq window they cover), branch.rebased (one event per branch per update-from-parent: the branch re-anchored onto new parent state, so re-read it — its already-delivered changes are never re-reported) and the branch review workflow (branch.created, branch.ready_for_review, branch.approved, branch.rejected, branch.merged, …, each naming the branch, its merge target and the people involved). Poll without a cursor to read from the beginning, or with start=now to receive an empty page whose next_cursor is the present (future events only, no history replayed); then store and pass back next_cursor: pages are bounded by the stream’s settled floor, so a stored cursor never skips an event that commits late. Delivery order follows next_cursor; occurred_at can be out of order across pages (historical imports carry past timestamps). Filter by comma-separated type and/or one branch (branch= or branch=master for Base); a cursor minted under a filter admits that filter or a narrower one — widening is a 400 instead of a silent skip of the excluded events, so restart from an earlier cursor to widen. Events carry the project, branch ("master" means Base), actor and an app_url back into Flow. ## OpenAPI ````yaml /openapi/customer-api.json get /project/{projectId}/events openapi: 3.0.0 info: contact: {} description: >- Flow customer API reference. Start with the [quickstart](/api/quickstart) and [authentication guide](/api/authentication). title: Customer API version: 1.0.0 servers: - description: Flow API url: '{baseUrl}' variables: baseUrl: default: https://backend.branch.flowengineering.com security: [] tags: - name: Audit - name: Automations - name: Branches - name: Comments - name: Convert - name: Data Model - name: Diagrams - name: Entities - name: Events - name: Files - name: Import - name: Notifications - name: Persistent agents - name: Projects - name: ReqIF - name: ReqIF Import - name: Review policy - name: Shared Access Grants - name: User Groups - name: Users paths: /project/{projectId}/events: get: tags: - Events summary: Read the project event stream description: >- Engineering events for one project in delivery order: branch.changed (item changes on a branch or Base, one event per branch and actor within the page, with the touched entity ids and the origin diff-seq window they cover), branch.rebased (one event per branch per update-from-parent: the branch re-anchored onto new parent state, so re-read it — its already-delivered changes are never re-reported) and the branch review workflow (branch.created, branch.ready_for_review, branch.approved, branch.rejected, branch.merged, …, each naming the branch, its merge target and the people involved). Poll without a cursor to read from the beginning, or with start=now to receive an empty page whose next_cursor is the present (future events only, no history replayed); then store and pass back next_cursor: pages are bounded by the stream’s settled floor, so a stored cursor never skips an event that commits late. Delivery order follows next_cursor; occurred_at can be out of order across pages (historical imports carry past timestamps). Filter by comma-separated type and/or one branch (branch= or branch=master for Base); a cursor minted under a filter admits that filter or a narrower one — widening is a 400 instead of a silent skip of the excluded events, so restart from an earlier cursor to widen. Events carry the project, branch ("master" means Base), actor and an app_url back into Flow. operationId: ProjectEventsController_list parameters: - in: path name: projectId required: true schema: type: string - description: >- The next_cursor of the previous page. Omit it to read from the beginning, or pass start=now instead to begin at the present. A cursor admits the type filter it was minted under and any narrower one; a wider filter is a 400 — restart from an earlier cursor to widen. in: query name: cursor required: false schema: type: string - description: >- start=now answers an empty page whose next_cursor is the present: poll from it to receive only events that happen after this call, without replaying history. Takes no cursor; the minted cursor is unfiltered, so it admits any later type filter. in: query name: start required: false schema: enum: - now type: string - in: query name: limit required: false schema: default: 50 maximum: 200 minimum: 1 type: number - description: >- Comma-separated event types to include (branch.changed, branch.rebased, branch.created, branch.ready_for_review, branch.draft, branch.approved, branch.rejected, branch.review_cleared, branch.reviewer_removed, branch.owner_changed, branch.editor_groups_changed, branch.approval_dismissed, branch.admin_bypass, branch.closed, branch.reopened, branch.merged, branch.extracted, branch.extraction_undone). Omit to read every type. in: query name: type required: false schema: type: string - description: >- Only events of one branch: a branch id, or "master" for Base. Omit to read every branch. Like type, a cursor minted under a branch admits only that branch (a wider poll is a 400). in: query name: branch required: false schema: type: string - description: Workspace identifier in: header name: customer required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ProjectEventPageDto' description: '' security: - api-key: [] - bearer: [] components: schemas: ProjectEventPageDto: properties: events: items: $ref: '#/components/schemas/ProjectEventDto' type: array more_available: description: >- True when this page filled the requested limit and more settled events wait beyond it. type: boolean next_cursor: description: >- Position from which the next read continues. Pass it back as cursor. It is a checkpoint, not merely the last delivered event: when the page is short it is the stream’s settled floor, so nothing at or below it can appear later. type: string required: - events - next_cursor - more_available type: object ProjectEventDto: properties: actor: $ref: '#/components/schemas/ProjectEventActorDto' app_url: description: >- Absolute URL of the event’s subject in Flow: the branch’s table for branch.changed, its review otherwise. type: string branch_id: description: Branch the event belongs to; "master" means Base. type: string event_type: enum: - branch.changed - branch.rebased - branch.created - branch.ready_for_review - branch.draft - branch.approved - branch.rejected - branch.review_cleared - branch.reviewer_removed - branch.owner_changed - branch.editor_groups_changed - branch.approval_dismissed - branch.admin_bypass - branch.closed - branch.reopened - branch.merged - branch.extracted - branch.extraction_undone type: string occurred_at: description: >- The recorded time of the event. Informational: delivery order follows next_cursor, and occurred_at can be out of order across pages (historical imports carry past timestamps), so order by delivery, not by this field. format: date-time type: string payload: oneOf: - $ref: '#/components/schemas/BranchChangedPayloadDto' - $ref: '#/components/schemas/BranchReviewPayloadDto' - $ref: '#/components/schemas/BranchRebasedPayloadDto' project_id: type: string required: - event_type - occurred_at - project_id - branch_id - actor - app_url - payload type: object ProjectEventActorDto: properties: id: description: User or agent ID. Omitted for system actors. type: string type: enum: - user - agent - system type: string required: - type type: object BranchChangedPayloadDto: properties: diff_count: description: Item diffs this event covers (cascades excluded). type: number entity_count: type: number entity_ids: description: Touched entity ids, at most 100; see truncated. items: type: string type: array first_seq_id: description: >- Origin seq of the first diff this event covers: the position the write entered the log, stable across rebases. type: string last_seq_id: description: Origin seq of the last diff this event covers. type: string truncated: type: boolean required: - diff_count - entity_count - entity_ids - truncated - first_seq_id - last_seq_id type: object BranchReviewPayloadDto: properties: baseline_id: description: The baseline a merge produced. type: string branch_name: type: string comment_id: description: The review comment attached to the decision. type: string review_event_id: description: ID of the review-history row; stable across reads. type: string subject_user_group_id: type: string subject_user_group_name: type: string subject_user_id: description: >- The user the event is about when it is not the actor (a dismissed approval, a removed reviewer, a new owner). type: string target_branch_id: description: >- The branch’s merge target as the event recorded it, else its current parent; null means Base. nullable: true type: string required: - review_event_id - branch_name - target_branch_id type: object BranchRebasedPayloadDto: properties: branch_name: type: string parent_branch_id: description: The branch the branch re-anchored onto; null means Base. nullable: true type: string parent_seq_id: description: >- The fork point the branch moved to (its parent_seq_id after the rebase). nullable: true type: string rebase_event_id: description: ID of the rebase-history row; stable across reads. type: string required: - rebase_event_id - branch_name - parent_branch_id - parent_seq_id type: object securitySchemes: api-key: in: header name: X-API-Key type: apiKey bearer: bearerFormat: JWT scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.