> ## Documentation Index > Fetch the complete documentation index at: https://docs.contraforce.com/llms.txt > Use this file to discover all available pages before exploring further. # Get reporting agent investigations ## OpenAPI ````yaml /api-reference/openapi.json post /api/v2/reporting/agent-investigations openapi: 3.1.1 info: title: ContraForce API description: ContraForce platform API for security operations management. version: '2.0' servers: [] security: [] tags: - name: Incidents - name: Gamebooks - name: Data sources - name: Service tickets - name: Investigation - name: Export - name: agent-tools - name: Cross-workspace incidents - name: Cross-workspace gamebooks - name: Cross-workspace data sources - name: Webhooks - name: Service accounts - name: Users - name: Azure resources - name: Reporting paths: /api/v2/reporting/agent-investigations: post: tags: - Reporting summary: Get reporting agent investigations operationId: v2-get-reporting-agent-investigations requestBody: content: application/json: schema: $ref: '#/components/schemas/ReportingReadRequest' responses: '200': description: OK content: application/json: schema: $ref: >- #/components/schemas/ApiResponseOfAgentInvestigationsReportResponse '400': description: Bad request — validation or parameter binding failed. content: application/problem+json: schema: $ref: '#/components/schemas/ApiProblemDetails' '401': description: Unauthorized — missing or invalid Bearer token. content: application/problem+json: schema: $ref: '#/components/schemas/ApiProblemDetails' '403': description: Forbidden — insufficient scope or workspace access. content: application/problem+json: schema: $ref: '#/components/schemas/ApiProblemDetails' '404': description: Not found — workspace or resource is missing. content: application/problem+json: schema: $ref: '#/components/schemas/ApiProblemDetails' '500': description: Internal server error. content: application/problem+json: schema: $ref: '#/components/schemas/ApiProblemDetails' components: schemas: ReportingReadRequest: required: - from - to type: object properties: from: type: string description: >- The first day of the range, inclusive (UTC days). A range spans at most 366 days. format: date to: type: string description: The last day of the range, inclusive (UTC days). format: date workspaceIds: type: - 'null' - array items: type: string format: uuid description: >- The workspaces to read, at most 500; `null` or empty reads every workspace the caller may see. A service account sees the workspaces it holds a role on. description: The day range and workspace selection every reporting read takes. ApiResponseOfAgentInvestigationsReportResponse: type: object properties: data: $ref: '#/components/schemas/AgentInvestigationsReportResponse' description: v2 agent investigation outcomes over time. meta: $ref: '#/components/schemas/ResponseMeta' description: Standard v2 API response envelope for single-item responses. ApiProblemDetails: type: object properties: type: type: - 'null' - string title: type: - 'null' - string status: pattern: ^-?(?:0|[1-9]\d*)$ type: - 'null' - integer - string format: int32 detail: type: - 'null' - string instance: type: - 'null' - string code: type: - 'null' - string requestId: type: - 'null' - string timestamp: type: - 'null' - string target: type: - 'null' - string errors: type: - 'null' - object additionalProperties: type: array items: type: string description: >- API extension of ProblemDetails that surfaces the stable error code, trace identifier, timestamp, optional target, and optional field-keyed validation error map alongside the RFC 7807 members. AgentInvestigationsReportResponse: type: object properties: granularity: type: - 'null' - string description: '`day` for ranges up to 92 days, otherwise `month`.' points: type: - 'null' - array items: $ref: '#/components/schemas/AgentInvestigationsPointResponse' description: >- Agent investigation totals for one day or month, or the whole range. description: >- One point per day or month in the range, oldest first; a period with no runs has zero counts and no durations. totals: $ref: '#/components/schemas/AgentInvestigationsPointResponse' description: Totals for the whole range. investigatedBySeverity: type: - 'null' - object additionalProperties: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string format: int32 description: Incidents investigated, by the incident's severity. investigatedByVerdict: type: - 'null' - object additionalProperties: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string format: int32 description: >- Incidents investigated, by the verdict their latest run reached; a run that reached none is not counted. feedbackBySignal: type: - 'null' - object additionalProperties: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string format: int32 description: >- Every feedback record on the investigations, by signal, including bulk and automated closes. scoredFeedbackBySignal: type: - 'null' - object additionalProperties: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string format: int32 description: >- The feedback records that count toward accuracy, by signal; accuracy is read from these alone. undeterminedScoredFeedbackBySignal: type: - 'null' - object additionalProperties: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string format: int32 description: >- The part of the scored records on runs where the agent answered Undetermined. Accuracy is stated over decided runs only, so it is read from the difference. verdictsReviewed: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: >- Incidents whose latest run reached a verdict that a person reviewed, out of the incidents by verdict. format: int32 runsWithVerdict: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: >- Runs that reached a verdict, re-runs included; how often the agent decides is stated per run. format: int32 decidedRuns: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: >- The part of the runs with a verdict whose verdict was True, Benign or False Positive. format: int32 costBasis: type: - 'null' - string description: >- How the account's runs are priced: `Compute`, where the compute spend is reported, `Billed` or `None`, where it is ContraForce's cost and withheld, or `Restricted` for a caller who may not see spend. read: $ref: '#/components/schemas/ReportingReadInfoResponse' description: How the response was read. description: v2 agent investigation outcomes over time. ResponseMeta: type: object properties: requestId: type: - 'null' - string timestamp: type: - 'null' - string AgentInvestigationsPointResponse: type: object properties: date: type: - 'null' - string description: '`yyyy-MM-dd` or `yyyy-MM`; empty for range totals.' runs: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: All terminal runs, including re-runs. format: int32 resolvedByAgent: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: Incidents whose latest run's submission closed them. format: int32 escalated: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: Incidents whose latest run left them for a person. format: int32 failed: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: Incidents whose latest run failed. format: int32 completedNoVerdict: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: Incidents whose latest run completed without a verdict. format: int32 noChange: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: >- Incidents whose latest run recommended closing them when they were already closed. format: int32 medianDurationSeconds: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$ type: - 'null' - number - string description: Median run duration in seconds; null when there were no runs. format: double p90DurationSeconds: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$ type: - 'null' - number - string description: >- 90th percentile run duration in seconds; null when there were no runs. format: double costUsd: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - 'null' - number - string description: >- The agents' compute spend in US dollars, or `null` where it is not the caller's to see. format: double totalTokens: pattern: ^-?(?:0|[1-9]\d*)$ type: - 'null' - integer - string description: >- Tokens the runs consumed, withheld with decimal? AgentInvestigationsPointResponse.CostUsd: priced at a model's rate, they are the spend. format: int64 description: Agent investigation totals for one day or month, or the whole range. ReportingReadInfoResponse: type: object properties: scope: type: - 'null' - string description: >- `account` when account-wide totals were read, otherwise `workspaces`. workspaceCount: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: Workspaces the response covers. format: int32 documentsRead: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: >- Aggregate documents read to build the response (0 when served from cache). format: int32 fromCache: type: boolean description: Whether the response came from the in-memory cache. authorizeMs: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$ type: - number - string description: >- Milliseconds this request spent validating the range and checking workspace access. format: double readMs: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$ type: - number - string description: >- Milliseconds spent loading aggregate documents (0 when served from cache). format: double description: How a reporting response was read, for load testing and diagnosis. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.