Event Reports

Event reports capture flow execution event data over a time window and produce a downloadable CSV once generation completes. Use them for compliance auditing, SLA reporting, and bulk error analysis.

The typical lifecycle is: create a report with target flow IDs and a time range, poll until status reaches completed, then download the CSV via a time-limited signed URL.

Event report schema

List event reports

get

/v1/eventreports

Returns all event report objects for the account. No pagination or filtering is supported — query parameters like eventReportId, _limit, and status are accepted but silently ignored.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Array of event report objects.

application/json

An event report captures flow execution event data for a set of flows over a specified time window. Once generation completes, the report can be downloaded as a CSV via a time-limited signed URL.

Status lifecycle: queued -> running -> completed | canceled

The reportGenerationErrors array may contain per-flow errors even when the overall status is completed. The _requestedByUserId field only appears on the POST create response; GET endpoints return requestedByUser (with name and email) instead.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyOptional

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_requestedByUserIdstring · objectIdRead-onlyOptional

The user ID of the person who requested the report.

Example: 60f1a2b3c4d5e6f7a8b9c0d1

typestring · enumRequired

The type of event report. Currently only flow_events is supported.

Example: flow_eventsPossible values:

_flowIdsstring · objectId[] · min: 1Required

Array of flow IDs whose events are included in the report. At least one flow ID is required.

Example: ["63a1b2c3d4e5f60011223344","63a1b2c3d4e5f60011223355"]

startTimestring · date-timeRequired

Start of the time window for the report. Must be within the last 30 days. ISO 8601 format.

Example: 2026-04-01T00:00:00.000Z

endTimestring · date-timeOptional

End of the time window for the report. Defaults to the current time if omitted. The span between startTime and endTime must not exceed 3 days.

Example: 2026-04-03T00:00:00.000Z

statusstring · enumRead-onlyRequired

Current status of the report generation.

Example: queuedPossible values:

startedAtstring · date-timeRead-onlyOptional

When report generation began. Present once the report enters running status.

Example: 2026-04-28T14:30:05.000Z

endedAtstring · date-timeRead-onlyOptional

When report generation finished. Only present on completed reports.

Example: 2026-04-28T14:32:00.000Z

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/eventreports

GET /v1/eventreports HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "682278b3e4b0a10012abcdef",
    "type": "flow_events",
    "_flowIds": [
      "63a1b2c3d4e5f60011223344"
    ],
    "startTime": "2026-04-27T00:00:00.000Z",
    "endTime": "2026-04-29T00:00:00.000Z",
    "status": "completed",
    "reportGenerationErrors": [],
    "createdAt": "2026-04-28T14:30:00.000Z",
    "startedAt": "2026-04-28T14:30:05.000Z",
    "endedAt": "2026-04-28T14:32:00.000Z",
    "requestedByUser": {
      "name": "Jane Doe",
      "email": "[e-mail]"
    }
  },
  {
    "_id": "682278b3e4b0a10012aaaaaa",
    "type": "flow_events",
    "_flowIds": [
      "63a1b2c3d4e5f60011223355"
    ],
    "startTime": "2026-04-28T00:00:00.000Z",
    "endTime": "2026-04-29T12:00:00.000Z",
    "status": "queued",
    "reportGenerationErrors": [],
    "createdAt": "2026-04-29T15:00:00.000Z",
    "requestedByUser": {
      "name": "Jane Doe",
      "email": "[e-mail]"
    }
  }
]

Create an event report

post

/v1/eventreports

Queues generation of a new event report for the specified flows and time window. The report is created in queued status and transitions through running to completed (or canceled).

startTime must be within the last 30 days and the span to endTime must not exceed 3 days. If endTime is omitted, the server defaults it to the current time. Poll GET /v1/eventreports/{_id} until status is completed, then download the CSV via GET /v1/eventreports/{_id}/signedURL. The create response includes _requestedByUserId; subsequent GET responses replace this with the requestedByUser object (name + email).

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Request body for creating a new event report. startTime must be within the last 30 days and the span to endTime must not exceed 3 days. If endTime is omitted, the server defaults it to the current time.

typestring · enumRequired

The type of event report to generate. Currently only flow_events is supported.

Example: flow_eventsPossible values:

_flowIdsstring · objectId[] · min: 1Required

Array of flow IDs whose events should be included in the report. At least one flow ID is required.

Example: ["63a1b2c3d4e5f60011223344"]

startTimestring · date-timeRequired

Start of the time window. Must be within the last 30 days. ISO 8601 format.

Example: 2026-04-01T00:00:00.000Z

endTimestring · date-timeOptional

End of the time window. Defaults to the current time if omitted. The total span (endTime - startTime) must not exceed 3 days.

Example: 2026-04-03T00:00:00.000Z

Responses

201

Event report created and queued for generation.

application/json

An event report captures flow execution event data for a set of flows over a specified time window. Once generation completes, the report can be downloaded as a CSV via a time-limited signed URL.

Status lifecycle: queued -> running -> completed | canceled

The reportGenerationErrors array may contain per-flow errors even when the overall status is completed. The _requestedByUserId field only appears on the POST create response; GET endpoints return requestedByUser (with name and email) instead.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyOptional

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_requestedByUserIdstring · objectIdRead-onlyOptional

The user ID of the person who requested the report.

Example: 60f1a2b3c4d5e6f7a8b9c0d1

typestring · enumRequired

The type of event report. Currently only flow_events is supported.

Example: flow_eventsPossible values:

_flowIdsstring · objectId[] · min: 1Required

Array of flow IDs whose events are included in the report. At least one flow ID is required.

Example: ["63a1b2c3d4e5f60011223344","63a1b2c3d4e5f60011223355"]

startTimestring · date-timeRequired

Start of the time window for the report. Must be within the last 30 days. ISO 8601 format.

Example: 2026-04-01T00:00:00.000Z

endTimestring · date-timeOptional

End of the time window for the report. Defaults to the current time if omitted. The span between startTime and endTime must not exceed 3 days.

Example: 2026-04-03T00:00:00.000Z

statusstring · enumRead-onlyRequired

Current status of the report generation.

Example: queuedPossible values:

startedAtstring · date-timeRead-onlyOptional

When report generation began. Present once the report enters running status.

Example: 2026-04-28T14:30:05.000Z

endedAtstring · date-timeRead-onlyOptional

When report generation finished. Only present on completed reports.

Example: 2026-04-28T14:32:00.000Z

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

post/v1/eventreports

POST /v1/eventreports HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 138

{
  "type": "flow_events",
  "_flowIds": [
    "63a1b2c3d4e5f60011223344"
  ],
  "startTime": "2026-04-27T00:00:00.000Z",
  "endTime": "2026-04-29T00:00:00.000Z"
}

{
  "_id": "682278b3e4b0a10012abcdef",
  "_requestedByUserId": "60f1a2b3c4d5e6f7a8b9c0d1",
  "type": "flow_events",
  "_flowIds": [
    "63a1b2c3d4e5f60011223344"
  ],
  "startTime": "2026-04-27T00:00:00.000Z",
  "endTime": "2026-04-29T00:00:00.000Z",
  "status": "queued",
  "reportGenerationErrors": [],
  "createdAt": "2026-04-29T14:30:00.000Z"
}

Get an event report

get

/v1/eventreports/{_id}

Returns a single event report by ID. Check status for completed before attempting to download via the signed URL. The reportGenerationErrors array may contain per-flow errors even when the overall status is completed.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Event report ID.

Example: 682278b3e4b0a10012abcdef

Responses

200

The event report record.

application/json

An event report captures flow execution event data for a set of flows over a specified time window. Once generation completes, the report can be downloaded as a CSV via a time-limited signed URL.

Status lifecycle: queued -> running -> completed | canceled

The reportGenerationErrors array may contain per-flow errors even when the overall status is completed. The _requestedByUserId field only appears on the POST create response; GET endpoints return requestedByUser (with name and email) instead.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyOptional

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_requestedByUserIdstring · objectIdRead-onlyOptional

The user ID of the person who requested the report.

Example: 60f1a2b3c4d5e6f7a8b9c0d1

typestring · enumRequired

The type of event report. Currently only flow_events is supported.

Example: flow_eventsPossible values:

_flowIdsstring · objectId[] · min: 1Required

Array of flow IDs whose events are included in the report. At least one flow ID is required.

Example: ["63a1b2c3d4e5f60011223344","63a1b2c3d4e5f60011223355"]

startTimestring · date-timeRequired

Start of the time window for the report. Must be within the last 30 days. ISO 8601 format.

Example: 2026-04-01T00:00:00.000Z

endTimestring · date-timeOptional

End of the time window for the report. Defaults to the current time if omitted. The span between startTime and endTime must not exceed 3 days.

Example: 2026-04-03T00:00:00.000Z

statusstring · enumRead-onlyRequired

Current status of the report generation.

Example: queuedPossible values:

startedAtstring · date-timeRead-onlyOptional

When report generation began. Present once the report enters running status.

Example: 2026-04-28T14:30:05.000Z

endedAtstring · date-timeRead-onlyOptional

When report generation finished. Only present on completed reports.

Example: 2026-04-28T14:32:00.000Z

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/eventreports/{_id}

GET /v1/eventreports/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "682278b3e4b0a10012abcdef",
  "type": "flow_events",
  "_flowIds": [
    "63a1b2c3d4e5f60011223344"
  ],
  "startTime": "2026-04-27T00:00:00.000Z",
  "endTime": "2026-04-29T00:00:00.000Z",
  "status": "completed",
  "reportGenerationErrors": [],
  "createdAt": "2026-04-28T14:30:00.000Z",
  "startedAt": "2026-04-28T14:30:05.000Z",
  "endedAt": "2026-04-28T14:32:00.000Z",
  "requestedByUser": {
    "name": "Jane Doe",
    "email": "[e-mail]"
  }
}

Get signed URL for an event report

get

/v1/eventreports/{_id}/signedURL

Returns a pre-signed S3 URL for downloading the completed event report as a CSV file. The URL is valid for approximately 15 minutes. Only works when the report status is completed -- requesting it in any other status returns 400. If the URL has expired, call this endpoint again to get a fresh one.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Event report ID.

Example: 682278b3e4b0a10012abcdef

Responses

200

Signed URL for CSV download.

application/json

Response containing a pre-signed S3 URL for downloading the completed event report CSV. The URL is valid for approximately 15 minutes and should be consumed immediately. Only returned when the report status is completed.

signedURLstring · uriOptional

Pre-signed S3 URL for downloading the report CSV. Valid for approximately 15 minutes from generation.

Example: https://integrator-event-reports.s3.us-east-1.amazonaws.com/_682278b3e4b0a10012abcdef.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&...

400

The report is not in completed status.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/eventreports/{_id}/signedURL

GET /v1/eventreports/{_id}/signedURL HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "signedURL": "https://integrator-event-reports.s3.us-east-1.amazonaws.com/_682278b3e4b0a10012abcdef.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=abc123"
}

Cancel an event report

put

/v1/eventreports/{_id}/cancel

Cancels a queued or running event report. The report's status transitions to canceled. No request body is needed. Idempotent for reports already in canceled status. A completed report cannot be canceled, and canceled reports cannot be resumed -- create a new one instead.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Event report ID to cancel.

Example: 682278b3e4b0a10012abcdef

Responses

204

Event report canceled successfully.

No content

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

The report is in completed status and cannot be canceled.

application/json

put/v1/eventreports/{_id}/cancel

PUT /v1/eventreports/{_id}/cancel HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content