> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neoagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Petra Security API

> Read Petra Security from Neo: Microsoft 365 compromise incidents, failed sign-in attacks, posture reports, tenants, usage and billable users

The common uses are a compromise ticket, where the agent adds Petra's incident to the ticket (the compromised user, the phishing email, the remediation status), a quarterly business review, where it summarizes a client's failed attacks and posture risks, and a monthly billing check, where it compares Petra's billable users per client with what you bill.

<Info>
  Automatically enabled when you configure Petra Security permissions in your agent workflow.
</Info>

## What It Does

* Read a client's incidents: the compromised user, when it happened, the dwell time, the remediation status, and the phishing email with the other mailboxes that received it
* Read a client's failed sign-in attacks over any period, by country, by day and attack type, and the most targeted users
* Read a client's latest posture report, or its history: score and grade, control results, the Global Administrators review, top risks and suggested fixes
* Read your Petra tenants, their usage and billing status, and each tenant's billable users

Neo only reads Petra Security.

## Permission Groups

| Group | Covers |
| - | - |
| Tenants and Usage | Your Petra tenants with their Microsoft tenant IDs, usage and billing status, and each tenant's billable users (read only) |
| Incidents | Account-compromise incidents, with the user, the phishing email and the remediation status (read only) |
| Failed Attacks | Failed sign-in attacks per tenant over a date range (read only) |
| Posture Reports | Completed Microsoft 365 posture reports per tenant (read only) |

## Access Profile

| Profile | What runs |
| - | - |
| **Read Only** | Every read in the four groups |

## Safety Controls

| Control | Behavior |
| - | - |
| **The ticket's client only** | On a run for a ticket that names a company, Neo sends a call only when it names, in `tenantId`, the Petra tenant the ticket's company is mapped to. The tenant list, usage, and a read without `tenantId` name every client, so Neo does not send them on such a run. A run with no ticket company, such as a chat with Neo, a scheduled agent or a ticket that names no company, is not narrowed |
| **Refused** | The usage spreadsheet download (`v1/usage-xlsx`), which answers a file. `v1/usage` gives tenant usage |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.