> ## 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).
For common API errors, see [API Troubleshooting](/api-reference/troubleshooting).
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: 48f3708e-45c1-4902-9e3b-26165bf3d76a
url: >-
https://app.petrasecurity.com/tenant/ZZk90t/incidents/48f3708e-45c1-4902-9e3b-26165bf3d76a
createdAt: '2025-02-06T03:55:06.050Z'
occurredAt: '2025-02-04T22:14:12.000Z'
remediationStatus: REMEDIATED
isLive: false
dwellTimeMinutes: 1918.650583333333
tenant:
petraTenantId: ZZk90t
name: Acme Corp.
microsoftTenantId: a1b2c3d4-5e6f-7890-abcd-ef1234567890
user:
id: 2e8c5169-af3d-447b-9c4f-82d516b9fe34
userPrincipalName: askywalker@acmecorp.com
mail: askywalker@acmecorp.com
displayName: Anakin Skywalker
accountEnabled: true
lastPasswordChangeDateTime: null
- id: 0c207800-80d0-46ed-beec-376779e33bbb
url: >-
https://app.petrasecurity.com/tenant/ZZk90t/incidents/0c207800-80d0-46ed-beec-376779e33bbb
createdAt: '2025-02-05T23:38:05.705Z'
occurredAt: '2025-02-05T23:33:29.000Z'
remediationStatus: REMEDIATED
isLive: true
dwellTimeMinutes: 5.923883333333333
tenant:
petraTenantId: ZZk90t
name: Acme Corp.
microsoftTenantId: a1b2c3d4-5e6f-7890-abcd-ef1234567890
user:
id: 7a3fd851-bc4e-489c-b6d2-35f940d7ace2
userPrincipalName: ncaffrey@acmecorp.com
mail: ncaffrey@acmecorp.com
displayName: Neal Caffrey
accountEnabled: true
lastPasswordChangeDateTime: '2024-01-23T18:52:24.000Z'
- id: 6f604112-3dbc-4c85-9a87-e451e58d0286
url: >-
https://app.petrasecurity.com/tenant/ZZk90t/incidents/6f604112-3dbc-4c85-9a87-e451e58d0286
createdAt: '2025-01-26T14:02:43.050Z'
occurredAt: '2025-01-22T22:20:57.000Z'
remediationStatus: REMEDIATED
isLive: false
dwellTimeMinutes: 656634.6116
tenant:
petraTenantId: ZZk90t
name: Acme Corp.
microsoftTenantId: a1b2c3d4-5e6f-7890-abcd-ef1234567890
user:
id: 0e50012e-ada7-42fa-bca2-754070f958a3
userPrincipalName: nick.renner@acmecorp.com
mail: nick.renner@acmecorp.com
displayName: Nick Renner
accountEnabled: true
lastPasswordChangeDateTime: null
- id: a212087c-bc60-4fbc-8bf5-5a4c2f823e5f
url: >-
https://app.petrasecurity.com/tenant/ZZk90t/incidents/a212087c-bc60-4fbc-8bf5-5a4c2f823e5f
createdAt: '2025-01-20T12:33:15.000Z'
occurredAt: '2025-01-20T12:28:47.000Z'
remediationStatus: REMEDIATED
isLive: true
dwellTimeMinutes: 4.55
tenant:
petraTenantId: ZZk90t
name: Acme Corp.
microsoftTenantId: a1b2c3d4-5e6f-7890-abcd-ef1234567890
user:
id: 01be85ac-1cbd-47a4-bead-47fc8c2c65da
userPrincipalName: asha.streich@acmecorp.com
mail: asha.streich@acmecorp.com
displayName: Asha Streich
accountEnabled: true
lastPasswordChangeDateTime: '2025-02-04T20:35:25.000Z'
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'
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
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer token authentication. Include your API key in the Authorization
header as 'Bearer YOUR_API_KEY'
````