> ## Documentation Index > Fetch the complete documentation index at: https://docs.petrasecurity.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Incidents > Retrieve security incidents ordered by creation date (newest first). > [!NOTE] > > For common API errors, see [API Troubleshooting](https://docs.petrasecurity.com/docs/api-reference/troubleshooting.md). > [!NOTE] > > This route is limited to **10 requests per minute**. ## OpenAPI ````yaml GET /v1/incidents openapi: 3.0.3 info: title: Petra Security API description: >- The Petra Security API provides programmatic access to security data and functionality within your Petra portal. version: 1.0.0 contact: name: Petra Security Support email: support@petrasecurity.com servers: - url: https://api.petrasecurity.com description: Production server security: - bearerAuth: [] paths: /v1/incidents: get: tags: [] summary: Get incidents description: Retrieve security incidents ordered by creation date (newest first). operationId: getIncidents parameters: - name: tenantId in: query required: false description: >- Filter incidents to a specific tenant. Accepts either a Petra tenant ID or a Microsoft tenant ID. You can find a tenant's Petra ID in the URL when viewing a tenant in the dashboard (e.g. app.petrasecurity.com/tenant/). You can also pass a Microsoft tenant ID and the endpoint will resolve it automatically. schema: type: string - name: startDate in: query required: false description: >- Only return incidents created on or after this date. Accepts ISO 8601 format — either date only (e.g. 2026-03-01) or full date-time (e.g. 2026-03-05T00:53:10.402Z). schema: type: string format: date-time - name: limit in: query required: false description: Maximum number of incidents to return. Defaults to 100, maximum 500. schema: type: integer default: 100 minimum: 1 maximum: 500 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetIncidentsResponse' '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found - The specified tenant was not found in your organization content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Requests - Rate limit exceeded for this route content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: GetIncidentsResponse: type: object properties: incidents: type: array description: Array of incident objects items: $ref: '#/components/schemas/IncidentResponse' example: incidents: - id: a212087c-bc60-4fbc-8bf5-5a4c2f823e5f url: >- https://app.petrasecurity.com/tenant/ZZk90t/incidents/a212087c-bc60-4fbc-8bf5-5a4c2f823e5f createdAt: '2026-01-20T12:33:15.000Z' occurredAt: '2026-01-20T12:28:47.000Z' remediationStatus: REMEDIATED isLive: true dwellTimeMinutes: 4.483333333333333 tenant: petraTenantId: ZZk90t name: Acme Corp. microsoftTenantId: '' user: id: 01be85ac-1cbd-47a4-bead-47fc8c2c65da userPrincipalName: asha.streich@acmecorp.com mail: asha.streich@acmecorp.com displayName: Asha Streich accountEnabled: true lastPasswordChangeDateTime: '2026-02-04T20:35:25.000Z' phishingEmail: subject: >- [EXTERNAL] Brad Smith shared "ConEd LLC Due Pay Application" with you sender: address: brad.smith@conedaccting.com displayName: Brad Smith from: address: brad.smith@conedaccting.com displayName: Brad Smith internetMessageId: <50khgaf2-qxez-35l9-jwmu-cbvqs8tvqibi@conedaccting.com> sentAt: '2026-01-20T11:39:47.000Z' receivedAt: '2026-01-20T11:59:52.000Z' hasAttachments: false sizeInBytes: null originalLocation: \Inbox currentLocation: Hard Deleted otherRecipients: - henry.braun@acmecorp.com - holly.connelly@acmecorp.com similarPhishes: - internetMessageId: <50khgaf2-qxez-35l9-jwmu-cbvqs8tvqibi@conedaccting.com> recipientUpn: henry.braun@acmecorp.com matchType: SAME_MESSAGE currentLocation: Hard Deleted - internetMessageId: <50khgaf2-qxez-35l9-jwmu-cbvqs8tvqibi@conedaccting.com> recipientUpn: asha.streich@acmecorp.com matchType: SAME_MESSAGE currentLocation: Hard Deleted - internetMessageId: <50khgaf2-qxez-35l9-jwmu-cbvqs8tvqibi@conedaccting.com> recipientUpn: holly.connelly@acmecorp.com matchType: SAME_MESSAGE currentLocation: Hard Deleted - id: 6f604112-3dbc-4c85-9a87-e451e58d0286 url: >- https://app.petrasecurity.com/tenant/ZZk90t/incidents/6f604112-3dbc-4c85-9a87-e451e58d0286 createdAt: '2026-01-26T14:02:43.050Z' occurredAt: '2026-01-22T22:20:57.000Z' remediationStatus: REMEDIATED isLive: false dwellTimeMinutes: 2902.766666666667 tenant: petraTenantId: ZZk90t name: Acme Corp. microsoftTenantId: '' user: id: 0e50012e-ada7-42fa-bca2-754070f958a3 userPrincipalName: nick.renner@acmecorp.com mail: nick.renner@acmecorp.com displayName: Nick Renner accountEnabled: true lastPasswordChangeDateTime: null phishingEmail: subject: Amended acme corp employee handbook sender: address: admin@astoriahotel.ig displayName: Admin from: address: admin@astoriahotel.ig displayName: Admin internetMessageId: <6cb64061-1df2-4cee-9bb2-1aacf7bb36d7@astoriahotel.ig> sentAt: '2026-01-22T22:26:15.000Z' receivedAt: '2026-01-22T22:28:20.000Z' hasAttachments: false sizeInBytes: null originalLocation: \Inbox currentLocation: Hard Deleted otherRecipients: [] similarPhishes: [] - id: 0776897d-be9d-4785-82b1-e240e64f2476 url: >- https://app.petrasecurity.com/tenant/ZZk90t/incidents/0776897d-be9d-4785-82b1-e240e64f2476 createdAt: '2026-07-19T16:55:41.242Z' occurredAt: '2026-05-21T17:11:00.000Z' remediationStatus: REMEDIATED_PRIOR_TO_ONBOARDING isLive: false dwellTimeMinutes: 60560.75 tenant: petraTenantId: ZZk90t name: Acme Corp. microsoftTenantId: '' user: id: bd4c7662-b0aa-4869-a57a-74ca66279e80 userPrincipalName: fleta.rowe@acmecorp.com mail: fleta.rowe@acmecorp.com displayName: Fleta Rowe accountEnabled: true lastPasswordChangeDateTime: '2026-07-06T13:14:32.000Z' phishingEmail: null - id: 3d71683e-5032-478a-b8c8-16c7e1073446 url: >- https://app.petrasecurity.com/tenant/ZZk90t/incidents/3d71683e-5032-478a-b8c8-16c7e1073446 createdAt: '2026-07-09T07:22:19.480Z' occurredAt: '2026-06-02T23:26:52.000Z' remediationStatus: REMEDIATED isLive: false dwellTimeMinutes: 63225.58333333334 tenant: petraTenantId: ZZk90t name: Acme Corp. microsoftTenantId: '' user: id: 35e895d1-6d5d-4919-9a50-69383bc4558e userPrincipalName: misael.ledner@acmecorp.com mail: misael.ledner@acmecorp.com displayName: Misael Ledner accountEnabled: true lastPasswordChangeDateTime: '2026-07-16T16:27:46.000Z' phishingEmail: null - id: 48f3708e-45c1-4902-9e3b-26165bf3d76a url: >- https://app.petrasecurity.com/tenant/ZZk90t/incidents/48f3708e-45c1-4902-9e3b-26165bf3d76a createdAt: '2026-02-06T03:55:06.050Z' occurredAt: '2026-02-04T22:14:12.000Z' remediationStatus: REMEDIATED isLive: false dwellTimeMinutes: 1918.650583333333 tenant: petraTenantId: ZZk90t name: Acme Corp. microsoftTenantId: '' user: id: 2e8c5169-af3d-447b-9c4f-82d516b9fe34 userPrincipalName: askywalker@acmecorp.com mail: askywalker@acmecorp.com displayName: Anakin Skywalker accountEnabled: true lastPasswordChangeDateTime: null phishingEmail: null - id: 0c207800-80d0-46ed-beec-376779e33bbb url: >- https://app.petrasecurity.com/tenant/ZZk90t/incidents/0c207800-80d0-46ed-beec-376779e33bbb createdAt: '2026-02-05T23:38:05.705Z' occurredAt: '2026-02-05T23:33:29.000Z' remediationStatus: REMEDIATED isLive: true dwellTimeMinutes: 4.707216666666667 tenant: petraTenantId: ZZk90t name: Acme Corp. microsoftTenantId: '' user: id: 7a3fd851-bc4e-489c-b6d2-35f940d7ace2 userPrincipalName: ncaffrey@acmecorp.com mail: ncaffrey@acmecorp.com displayName: Neal Caffrey accountEnabled: true lastPasswordChangeDateTime: '2025-01-23T18:52:24.000Z' phishingEmail: null ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Error code message: type: string description: Human-readable error message details: type: string description: Additional error details example: error: code: UNAUTHORIZED message: Invalid API key details: The provided API key is invalid or has been revoked IncidentResponse: type: object properties: id: type: string description: Unique identifier for the incident url: type: string description: Direct link to the incident in the Petra dashboard createdAt: type: string format: date-time description: When the incident was created in Petra (ISO 8601) occurredAt: type: string format: date-time description: When the underlying Microsoft event occurred (ISO 8601) remediationStatus: type: string description: Current remediation status of the incident enum: - REMEDIATED - PARTIALLY_REMEDIATED - UNREMEDIATED - INCORRECT - LOCKED_AWAITING_PASSWORD_RESET - UNCOVERED_IN_BASELINING - REMEDIATED_PRIOR_TO_ONBOARDING - PEN_TEST - ATTACKER_RETAINS_PASSWORD isLive: type: boolean description: >- Whether this is a live (real-time) incident or a historical one discovered during onboarding dwellTimeMinutes: type: number nullable: true description: Estimated attacker dwell time in minutes, if available tenant: $ref: '#/components/schemas/IncidentTenant' user: $ref: '#/components/schemas/IncidentUser' phishingEmail: $ref: '#/components/schemas/IncidentPhishingEmail' IncidentTenant: type: object properties: petraTenantId: type: string description: >- The Petra tenant ID (found in the dashboard URL: app.petrasecurity.com/tenant/) name: type: string description: Display name of the tenant microsoftTenantId: type: string description: The Microsoft tenant ID IncidentUser: type: object properties: id: type: string description: Unique identifier for the user userPrincipalName: type: string nullable: true description: The user's principal name (typically their email/login) mail: type: string nullable: true description: The user's email address displayName: type: string nullable: true description: The user's display name accountEnabled: type: boolean nullable: true description: Whether the user account is currently enabled lastPasswordChangeDateTime: type: string nullable: true description: When the user's password was last changed (ISO 8601), if available IncidentPhishingEmail: type: object nullable: true description: >- The phishing email that caused the incident. Null when the incident has no associated phish or the email data is unavailable. properties: subject: type: string nullable: true description: Subject line of the phishing email sender: $ref: '#/components/schemas/IncidentEmailParty' from: $ref: '#/components/schemas/IncidentEmailParty' internetMessageId: type: string nullable: true description: Internet Message ID of the phishing email sentAt: type: string format: date-time nullable: true description: When the email was sent (ISO 8601) receivedAt: type: string format: date-time nullable: true description: When the email was received (ISO 8601) hasAttachments: type: boolean nullable: true description: Whether the email has attachments sizeInBytes: type: integer nullable: true description: Size of the email in bytes, if available originalLocation: type: string nullable: true description: Mailbox folder the email was originally delivered to, if known currentLocation: type: string nullable: true description: >- Current mailbox folder of the email, if known (e.g. Inbox, Junk Email, Quarantine, Hard Deleted) otherRecipients: type: array items: type: string description: >- Other mailboxes in the tenant that received this email (excludes the compromised user) similarPhishes: type: array items: $ref: '#/components/schemas/SimilarPhishItem' description: >- Copies of this phish and similar-subject emails found in other mailboxes in the tenant. Capped at 500 entries. IncidentEmailParty: type: object description: >- An email address party. Used for both sender (the 'on behalf of' party) and from, which may differ. properties: address: type: string nullable: true description: Email address displayName: type: string nullable: true description: Display name, if available SimilarPhishItem: type: object description: >- A copy of the phishing email found in another mailbox in the tenant, or an email with a similar subject properties: internetMessageId: type: string nullable: true description: Internet Message ID of the matching email recipientUpn: type: string description: User principal name of the mailbox the email was delivered to matchType: type: string enum: - SAME_MESSAGE - SIMILAR_SUBJECT description: >- SAME_MESSAGE = same internetMessageId as the incident's phish; SIMILAR_SUBJECT = same subject (ignoring Re:/Fwd: prefixes) within the incident time window currentLocation: type: string nullable: true description: >- Current mailbox folder of the email, if known (e.g. Inbox, Junk Email, Quarantine, Hard Deleted) securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer token authentication. Include your API key in the Authorization header as 'Bearer YOUR_API_KEY' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.