# Event Reports ## List event reports > Returns an array of event report objects for the account.\ > \ > AI guidance:\ > \- The \`eventReportId\` query parameter filters the list to a single\ > report (still returned as an array).\ > \- The \`\_limit\` and \`status\` query parameters are accepted but currently\ > ignored by the server -- all reports are returned regardless.\ > \- The list response does not include the \`requestedByUser\` object;\ > use \`GET /v1/eventreports/{\_id}\` for that detail. ```json {"openapi":"3.1.0","info":{"title":"Event Reports","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"EventReport":{"type":"object","description":"An event report captures flow execution event data for a set of flows over\na specified time window. Once generation completes, the report can be\ndownloaded as a CSV via a time-limited signed URL.\n\n**Status lifecycle:** `queued` -> `running` -> `completed` | `canceled`\n\nAI guidance:\n- Poll `GET /v1/eventreports/{_id}` until `status` is `completed` before\n attempting to download via the signed URL endpoint.\n- The `reportGenerationErrors` array may contain per-flow errors even when\n the overall status is `completed` -- always check it.\n- The `requestedByUser` object (with `name` and `email`) is only present\n on the GET-by-ID response, not in the list response.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the event report."},"_requestedByUserId":{"type":"string","format":"objectId","readOnly":true,"description":"The user ID of the person who requested the report."},"type":{"type":"string","description":"The type of event report. Currently only `flow_events` is supported.\n","enum":["flow_events"]},"_flowIds":{"type":"array","description":"Array of flow IDs whose events are included in the report. At least\none flow ID is required.\n","items":{"type":"string","format":"objectId"}},"startTime":{"type":"string","format":"date-time","description":"Start of the time window for the report. Must be within the last\n30 days. ISO 8601 format.\n"},"endTime":{"type":"string","format":"date-time","description":"End of the time window for the report. Defaults to the current time\nif omitted. The span between `startTime` and `endTime` must not\nexceed 3 days.\n"},"status":{"type":"string","readOnly":true,"description":"Current status of the report generation.\n\n- `queued` -- the report request has been accepted and is waiting to\n be processed.\n- `running` -- report generation is in progress.\n- `completed` -- the report CSV is ready for download.\n- `canceled` -- the report was canceled before completion.\n","enum":["queued","running","completed","canceled"]},"reportGenerationErrors":{"type":"array","readOnly":true,"description":"Errors encountered during report generation. May contain entries even\nwhen the overall status is `completed` (e.g. a single flow failed\nwhile others succeeded).\n","items":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."}}}},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"When the report request was created."},"startedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When report generation began. Present once the report enters `running` status."},"endedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When report generation finished. Present once the report reaches `completed` or `canceled` status."},"requestedByUser":{"type":"object","readOnly":true,"description":"The user who requested the report. Only present on the\n`GET /v1/eventreports/{_id}` response, not in list results.\n","properties":{"name":{"type":"string","description":"Display name of the requesting user."},"email":{"type":"string","format":"email","description":"Email address of the requesting user."}}}},"required":["_id","type","_flowIds","startTime","status"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/eventreports":{"get":{"operationId":"listEventReports","tags":["Event Reports"],"summary":"List event reports","description":"Returns an array of event report objects for the account.\n\nAI guidance:\n- The `eventReportId` query parameter filters the list to a single\n report (still returned as an array).\n- The `_limit` and `status` query parameters are accepted but currently\n ignored by the server -- all reports are returned regardless.\n- The list response does not include the `requestedByUser` object;\n use `GET /v1/eventreports/{_id}` for that detail.","parameters":[{"name":"eventReportId","in":"query","description":"Filter to a specific event report by ID. The result is still\nreturned as an array (with zero or one element).","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Array of event report objects.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EventReport"}}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}} ``` ## Create an event report > 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\`).\ > \ > AI guidance:\ > \- \`startTime\` must be within the last 30 days. Older values return 400.\ > \- The span between \`startTime\` and \`endTime\` must not exceed 3 days.\ > \- If \`endTime\` is omitted, the server defaults it to the current time.\ > \- At least one flow ID must be provided in \`\_flowIds\`.\ > \- After creating, poll \`GET /v1/eventreports/{\_id}\` until \`status\` is\ > \`completed\`, then download the CSV via\ > \`GET /v1/eventreports/{\_id}/signedURL\`.\ > \- The response returns \`status: "queued"\` with an empty\ > \`reportGenerationErrors\` array. ```json {"openapi":"3.1.0","info":{"title":"Event Reports","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"EventReportCreateRequest":{"type":"object","description":"Request body for creating a new event report.\n\nAI guidance:\n- `startTime` must be within the last 30 days. Requests with an older\n `startTime` are rejected with 400.\n- The span between `startTime` and `endTime` must not exceed 3 days.\n- If `endTime` is omitted, the server defaults it to the current time.\n- At least one flow ID must be provided in `_flowIds`.\n","properties":{"type":{"type":"string","description":"The type of event report to generate. Currently only `flow_events`\nis supported.\n","enum":["flow_events"]},"_flowIds":{"type":"array","description":"Array of flow IDs whose events should be included in the report.\nAt least one flow ID is required.\n","items":{"type":"string","format":"objectId"}},"startTime":{"type":"string","format":"date-time","description":"Start of the time window. Must be within the last 30 days.\nISO 8601 format.\n"},"endTime":{"type":"string","format":"date-time","description":"End of the time window. Defaults to the current time if omitted.\nThe total span (`endTime - startTime`) must not exceed 3 days.\n"}},"required":["type","startTime","_flowIds"]},"EventReport":{"type":"object","description":"An event report captures flow execution event data for a set of flows over\na specified time window. Once generation completes, the report can be\ndownloaded as a CSV via a time-limited signed URL.\n\n**Status lifecycle:** `queued` -> `running` -> `completed` | `canceled`\n\nAI guidance:\n- Poll `GET /v1/eventreports/{_id}` until `status` is `completed` before\n attempting to download via the signed URL endpoint.\n- The `reportGenerationErrors` array may contain per-flow errors even when\n the overall status is `completed` -- always check it.\n- The `requestedByUser` object (with `name` and `email`) is only present\n on the GET-by-ID response, not in the list response.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the event report."},"_requestedByUserId":{"type":"string","format":"objectId","readOnly":true,"description":"The user ID of the person who requested the report."},"type":{"type":"string","description":"The type of event report. Currently only `flow_events` is supported.\n","enum":["flow_events"]},"_flowIds":{"type":"array","description":"Array of flow IDs whose events are included in the report. At least\none flow ID is required.\n","items":{"type":"string","format":"objectId"}},"startTime":{"type":"string","format":"date-time","description":"Start of the time window for the report. Must be within the last\n30 days. ISO 8601 format.\n"},"endTime":{"type":"string","format":"date-time","description":"End of the time window for the report. Defaults to the current time\nif omitted. The span between `startTime` and `endTime` must not\nexceed 3 days.\n"},"status":{"type":"string","readOnly":true,"description":"Current status of the report generation.\n\n- `queued` -- the report request has been accepted and is waiting to\n be processed.\n- `running` -- report generation is in progress.\n- `completed` -- the report CSV is ready for download.\n- `canceled` -- the report was canceled before completion.\n","enum":["queued","running","completed","canceled"]},"reportGenerationErrors":{"type":"array","readOnly":true,"description":"Errors encountered during report generation. May contain entries even\nwhen the overall status is `completed` (e.g. a single flow failed\nwhile others succeeded).\n","items":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."}}}},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"When the report request was created."},"startedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When report generation began. Present once the report enters `running` status."},"endedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When report generation finished. Present once the report reaches `completed` or `canceled` status."},"requestedByUser":{"type":"object","readOnly":true,"description":"The user who requested the report. Only present on the\n`GET /v1/eventreports/{_id}` response, not in list results.\n","properties":{"name":{"type":"string","description":"Display name of the requesting user."},"email":{"type":"string","format":"email","description":"Email address of the requesting user."}}}},"required":["_id","type","_flowIds","startTime","status"]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/eventreports":{"post":{"operationId":"createEventReport","tags":["Event Reports"],"summary":"Create an event report","description":"Queues generation of a new event report for the specified flows and time\nwindow. The report is created in `queued` status and transitions through\n`running` to `completed` (or `canceled`).\n\nAI guidance:\n- `startTime` must be within the last 30 days. Older values return 400.\n- The span between `startTime` and `endTime` must not exceed 3 days.\n- If `endTime` is omitted, the server defaults it to the current time.\n- At least one flow ID must be provided in `_flowIds`.\n- After creating, poll `GET /v1/eventreports/{_id}` until `status` is\n `completed`, then download the CSV via\n `GET /v1/eventreports/{_id}/signedURL`.\n- The response returns `status: \"queued\"` with an empty\n `reportGenerationErrors` array.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventReportCreateRequest"}}}},"responses":{"201":{"description":"Event report created and queued for generation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventReport"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}} ``` ## Get an event report > Returns a single event report including all detail fields. This is the\ > only endpoint that returns the \`requestedByUser\` object (with \`name\`\ > and \`email\`), as well as the \`startedAt\` and \`endedAt\` timestamps.\ > \ > AI guidance:\ > \- Use this endpoint to poll report status. 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\`.\ > \- An invalid (non-ObjectId) \`\_id\` returns 400 \`invalid\_ref\`.\ > \- A valid but non-existent \`\_id\` returns 404 \`invalid\_ref\` with message\ > \`"EventReport not found."\`. ```json {"openapi":"3.1.0","info":{"title":"Event Reports","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"EventReport":{"type":"object","description":"An event report captures flow execution event data for a set of flows over\na specified time window. Once generation completes, the report can be\ndownloaded as a CSV via a time-limited signed URL.\n\n**Status lifecycle:** `queued` -> `running` -> `completed` | `canceled`\n\nAI guidance:\n- Poll `GET /v1/eventreports/{_id}` until `status` is `completed` before\n attempting to download via the signed URL endpoint.\n- The `reportGenerationErrors` array may contain per-flow errors even when\n the overall status is `completed` -- always check it.\n- The `requestedByUser` object (with `name` and `email`) is only present\n on the GET-by-ID response, not in the list response.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the event report."},"_requestedByUserId":{"type":"string","format":"objectId","readOnly":true,"description":"The user ID of the person who requested the report."},"type":{"type":"string","description":"The type of event report. Currently only `flow_events` is supported.\n","enum":["flow_events"]},"_flowIds":{"type":"array","description":"Array of flow IDs whose events are included in the report. At least\none flow ID is required.\n","items":{"type":"string","format":"objectId"}},"startTime":{"type":"string","format":"date-time","description":"Start of the time window for the report. Must be within the last\n30 days. ISO 8601 format.\n"},"endTime":{"type":"string","format":"date-time","description":"End of the time window for the report. Defaults to the current time\nif omitted. The span between `startTime` and `endTime` must not\nexceed 3 days.\n"},"status":{"type":"string","readOnly":true,"description":"Current status of the report generation.\n\n- `queued` -- the report request has been accepted and is waiting to\n be processed.\n- `running` -- report generation is in progress.\n- `completed` -- the report CSV is ready for download.\n- `canceled` -- the report was canceled before completion.\n","enum":["queued","running","completed","canceled"]},"reportGenerationErrors":{"type":"array","readOnly":true,"description":"Errors encountered during report generation. May contain entries even\nwhen the overall status is `completed` (e.g. a single flow failed\nwhile others succeeded).\n","items":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."}}}},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"When the report request was created."},"startedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When report generation began. Present once the report enters `running` status."},"endedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When report generation finished. Present once the report reaches `completed` or `canceled` status."},"requestedByUser":{"type":"object","readOnly":true,"description":"The user who requested the report. Only present on the\n`GET /v1/eventreports/{_id}` response, not in list results.\n","properties":{"name":{"type":"string","description":"Display name of the requesting user."},"email":{"type":"string","format":"email","description":"Email address of the requesting user."}}}},"required":["_id","type","_flowIds","startTime","status"]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/eventreports/{_id}":{"get":{"operationId":"getEventReportById","tags":["Event Reports"],"summary":"Get an event report","description":"Returns a single event report including all detail fields. This is the\nonly endpoint that returns the `requestedByUser` object (with `name`\nand `email`), as well as the `startedAt` and `endedAt` timestamps.\n\nAI guidance:\n- Use this endpoint to poll report status. Check `status` for\n `completed` before attempting to download via the signed URL.\n- The `reportGenerationErrors` array may contain per-flow errors even\n when the overall `status` is `completed`.\n- An invalid (non-ObjectId) `_id` returns 400 `invalid_ref`.\n- A valid but non-existent `_id` returns 404 `invalid_ref` with message\n `\"EventReport not found.\"`.","parameters":[{"name":"_id","in":"path","required":true,"description":"Event report ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"The event report record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventReport"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}} ``` ## Get signed URL for an event report > Returns a pre-signed S3 URL for downloading the completed event report\ > as a CSV file. The URL is valid for approximately 15 minutes.\ > \ > AI guidance:\ > \- This endpoint only works when the report \`status\` is \`completed\`.\ > Requesting the signed URL for a report in any other status returns\ > 400 with error code \`invalid\_status\`.\ > \- The URL expires after \~15 minutes. Fetch and stream immediately;\ > do not persist the URL for later use.\ > \- If the URL has expired, call this endpoint again to get a fresh one. ```json {"openapi":"3.1.0","info":{"title":"Event Reports","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"EventReportSignedUrlResponse":{"type":"object","description":"Response containing a pre-signed S3 URL for downloading the completed\nevent report CSV. The URL is valid for approximately 15 minutes.\n\nAI guidance:\n- Fetch and stream the CSV immediately -- do not persist the URL.\n- This endpoint only succeeds when the report `status` is `completed`.\n Requesting the signed URL for a non-completed report returns 400\n with error code `invalid_status`.\n","properties":{"signedURL":{"type":"string","format":"uri","description":"Pre-signed S3 URL for downloading the report CSV. Valid for\napproximately 15 minutes from generation.\n"}},"required":["signedURL"]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/eventreports/{_id}/signedURL":{"get":{"operationId":"getEventReportSignedUrl","tags":["Event Reports"],"summary":"Get signed URL for an event report","description":"Returns a pre-signed S3 URL for downloading the completed event report\nas a CSV file. The URL is valid for approximately 15 minutes.\n\nAI guidance:\n- This endpoint only works when the report `status` is `completed`.\n Requesting the signed URL for a report in any other status returns\n 400 with error code `invalid_status`.\n- The URL expires after ~15 minutes. Fetch and stream immediately;\n do not persist the URL for later use.\n- If the URL has expired, call this endpoint again to get a fresh one.","parameters":[{"name":"_id","in":"path","required":true,"description":"Event report ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Signed URL for CSV download.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventReportSignedUrlResponse"}}}},"400":{"description":"The report is not in `completed` status. Error code `invalid_status`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}} ``` ## Cancel an event report > Cancels a queued or running event report. The report's \`status\`\ > transitions to \`canceled\`.\ > \ > AI guidance:\ > \- No request body is needed.\ > \- This operation is idempotent for reports already in \`canceled\` status.\ > \- Attempting to cancel a \`completed\` report returns 422 with error code\ > \`invalid\_status\`.\ > \- After cancellation, the report cannot be resumed -- create a new one\ > instead. ```json {"openapi":"3.1.0","info":{"title":"Event Reports","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/eventreports/{_id}/cancel":{"put":{"operationId":"cancelEventReport","tags":["Event Reports"],"summary":"Cancel an event report","description":"Cancels a queued or running event report. The report's `status`\ntransitions to `canceled`.\n\nAI guidance:\n- No request body is needed.\n- This operation is idempotent for reports already in `canceled` status.\n- Attempting to cancel a `completed` report returns 422 with error code\n `invalid_status`.\n- After cancellation, the report cannot be resumed -- create a new one\n instead.","parameters":[{"name":"_id","in":"path","required":true,"description":"Event report ID to cancel.","schema":{"type":"string","format":"objectId"}}],"responses":{"204":{"description":"Event report canceled successfully."},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"description":"The report is in `completed` status and cannot be canceled. Error\ncode `invalid_status`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.celigo.com/api/api-reference/event-reports.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.