> ## 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 Failed Attacks
> Retrieve failed-attack data for a specific tenant. Returns attack counts by country, daily attack breakdowns by type, and the most targeted users for the requested date range.
For common API errors, see [API Troubleshooting](/api-reference/troubleshooting).
This route is limited to **1 request per minute**.
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.
## OpenAPI
````yaml GET /v1/failed-attacks
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/failed-attacks:
get:
tags: []
summary: Get failed attacks
description: >-
Retrieve failed-attack data for a specific tenant. Returns attack counts
by country, daily attack breakdowns by type, and the most targeted users
for the requested date range.
operationId: getFailedAttacks
parameters:
- name: tenantId
in: query
required: true
description: >-
The tenant to generate the report for. 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: >-
Start of the reporting window. Accepts ISO 8601 date or date-time
(e.g. 2026-03-01 or 2026-03-01T00:00:00Z). Defaults to 30 days
before endDate.
schema:
type: string
format: date-time
- name: endDate
in: query
required: false
description: >-
End of the reporting window. Accepts ISO 8601 date or date-time.
Defaults to now.
schema:
type: string
format: date-time
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/FailedAttacksResponse'
'400':
description: Bad Request - Invalid startDate or endDate
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'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:
FailedAttacksResponse:
type: object
properties:
dateRange:
type: object
properties:
startDate:
type: string
format: date-time
description: Start of the reporting window (ISO 8601)
endDate:
type: string
format: date-time
description: End of the reporting window (ISO 8601)
tenant:
type: object
description: The tenant this report covers
properties:
petraTenantId:
type: string
description: The Petra tenant ID
name:
type: string
description: The tenant display name
microsoftTenantId:
type: string
description: The Microsoft tenant ID
totalCount:
type: integer
description: Total number of failed attacks in the window
byCountry:
type: array
description: Failed attacks grouped by origin country
items:
type: object
properties:
name:
type: string
nullable: true
description: Human-readable country name (e.g. Russia)
countryCode:
type: string
description: ISO 3166-1 alpha-2 country code (e.g. RU)
count:
type: integer
byDay:
type: array
description: Daily breakdown of failed attacks grouped by attack type
items:
type: object
properties:
date:
type: string
format: date-time
byType:
type: array
items:
type: object
properties:
attackType:
type: string
enum:
- PIERCING_HORNET
- FRANTIC_HORNET
- HURRICANE_HORNET
- LEGACY_AUTH
- NODE_FETCH
- PYTHON
- AZURE_ACOM
- AZURE_AD_CONNECT
- AZURE_IDS_AUTH_PROVIDER
- IDS_LOCKED
- PASSWORD_SPRAY
description: The type of attack detected
count:
type: integer
topTargetedUsers:
type: array
description: Users most targeted by failed attacks
items:
type: object
properties:
userPrincipalName:
type: string
description: User's email address (UPN)
fullName:
type: string
nullable: true
jobTitle:
type: string
nullable: true
count:
type: integer
attackOriginCountries:
type: array
description: Countries the attacks originated from
items:
type: object
properties:
name:
type: string
nullable: true
description: Human-readable country name
countryCode:
type: string
description: ISO 3166-1 alpha-2 country code
example:
dateRange:
startDate: '2025-01-05T00:00:00.000Z'
endDate: '2025-02-25T00:00:00.000Z'
tenant:
petraTenantId: ZZk90t
name: Acme Corp.
microsoftTenantId: a1b2c3d4-5e6f-7890-abcd-ef1234567890
totalCount: 50471
byCountry:
- name: United States
countryCode: US
count: 11501
- name: China
countryCode: CN
count: 11349
- name: South Korea
countryCode: KR
count: 5184
byDay:
- date: '2025-01-05T00:00:00.000Z'
byType:
- attackType: LEGACY_AUTH
count: 11
- date: '2025-01-06T00:00:00.000Z'
byType:
- attackType: LEGACY_AUTH
count: 66
- attackType: PASSWORD_SPRAY
count: 30
- date: '2025-01-07T00:00:00.000Z'
byType:
- attackType: LEGACY_AUTH
count: 97
- attackType: PASSWORD_SPRAY
count: 42
topTargetedUsers:
- userPrincipalName: pink.jones@acmecorp.com
fullName: Pink Jones
jobTitle: Sales Representative
count: 4463
attackOriginCountries:
- name: India
countryCode: IN
- name: United Arab Emirates
countryCode: AE
- name: Portugal
countryCode: PT
- userPrincipalName: solon.doyle@acmecorp.com
fullName: Solon Doyle
jobTitle: Network Engineer
count: 2519
attackOriginCountries:
- name: China
countryCode: CN
- name: Russia
countryCode: RU
- name: South Korea
countryCode: KR
- userPrincipalName: annabel.ankunding@acmecorp.com
fullName: Annabel Ankunding
jobTitle: Sales Manager
count: 2466
attackOriginCountries:
- name: France
countryCode: FR
- name: Germany
countryCode: DE
- name: Spain
countryCode: ES
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
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer token authentication. Include your API key in the Authorization
header as 'Bearer YOUR_API_KEY'
````