Response types¶

What each method returns, as recorded from FortiAIGate 8.0.2. Every type is a TypedDict (import it from pyfortiaigate to annotate your own code); at runtime every record is a plain dict. All fields are optional: a field the appliance leaves out is absent, so read with .get() when in doubt.

The Actions page shows which method returns which type. Calls that could not be verified live (org-level writes such as invite, and ICAP logs) are untyped JSON.

Argument types¶

Aliases used in method signatures.

Name	Is	Meaning
`WsRef`	`str \\| Mapping`	A workspace: its id, its name, or its record
`Ref`	`str \\| Mapping`	A detector, guardrail, policy or key: id, name or record (a key also by its `faig_...` secret)
`Day`	`date \\| str`	A report date: a `date` or `"YYYY-MM-DD"`
`When`	`datetime \\| int`	A log time: a `datetime` (naive = UTC) or epoch milliseconds
`JSON`	`Any`	An untyped response: the decoded JSON as-is

Users & workspaces¶

Me¶

The logged-in user.

Field	Type	Meaning
`id`	str
`username`	str
`email`	str
`fullName`	str
`role`	str	Org role: `org_admin`, `org_member`, `super_admin`.
`orgId`	str
`authType`	str
`avatarUrl`	str \| None
`memberships`	list[dict[str, Any]]	`[{"workspaceId", "role"}]`.

User¶

Field	Type	Meaning
`id`	str
`email`	str
`fullName`	str
`orgRole`	str	The EFFECTIVE role (`workspace_admin` once they admin a workspace).
`orgRoleStored`	str	The org role actually assigned.
`authType`	str
`isActive`	bool
`isDefaultAccount`	bool
`canQuickSignIn`	bool
`createdAt`	str
`lastLogin`	str \| None
`keyCount`	int
`spend`	float
`orgCycleSpend`	float
`globalCycleSpend`	float
`otherCycleSpend`	float
`budget`	float \| None
`budgetCycle`	str \| None
`customUserBudget`	float \| None
`customUserBudgetCycle`	str \| None
`customUserBudgetUncapped`	bool
`workspaces`	list[UserWorkspace]
`keys`	list[Any]	`user(id)` only.

UserWorkspace¶

Field	Type	Meaning
`workspaceId`	str
`workspaceName`	str
`membershipRole`	str	`workspace_admin` or `workspace_member`.
`budget`	float \| None
`spend`	float
`orgCycleSpend`	float

Invitation¶

A pending invitation. FortiAIGate sends no email: hand the invitee the invitePath link, or accept it with accept_invite.

Field	Type	Meaning
`id`	str	What `accept_invite` and `revoke_invitation` take.
`orgRole`	str
`addresses`	list[InviteAddress]
`invitedBy`	str	The inviting user's id.
`invitedByName`	str
`invitePath`	str	`/invite/<id>` on the console.
`createdAt`	str
`expiresAt`	str	Seven days after `createdAt`.

InviteAddress¶

Field	Type	Meaning
`email`	str
`status`	str	`pending` until accepted.

AcceptedInvite¶

Field	Type	Meaning
`createdAccount`	bool
`email`	str
`role`	str
`csrfToken`	str	For the new user's own browser session; the client does not use it.

Workspace¶

A workspace as the org-admin list gives it.

Field	Type	Meaning
`id`	str
`workspaceName`	str
`organizationId`	str
`organization`	str
`spend`	float
`budget`	float \| None
`budgetCycle`	str
`tpm`	int \| None
`rpm`	int \| None
`memberCount`	int
`admins`	list[dict[str, Any]]	`[{"id", "name", "email"}]`.
`providerAccess`	list[ProviderAccess]
`modelGroups`	list[ModelGroup]
`createdAt`	str
`createdBy`	str
`grantedModelCount`	int
`credentialGaps`	list[Any]
`description`	str	`create_workspace` only, as are the fields below.
`policyIds`	list[str]
`defaultKeyBindings`	list[Any]
`updatedAt`	str

MyWorkspace¶

A workspace the caller belongs to.

Field	Type	Meaning
`id`	str
`workspaceName`	str
`organization`	str
`membershipRole`	str
`myBudget`	float \| None
`myBudgetCycle`	str \| None
`myKeyCount`	int

WorkspaceSettings¶

Field	Type	Meaning
`id`	str
`workspaceName`	str
`allowedModels`	list[str]	Public names of the models the workspace may use.
`allowedPolicies`	list[Any]
`allowedGuardrails`	list[Any]
`budget`	float \| None
`budgetCycle`	str
`defaultMemberBudget`	float \| None
`defaultMemberBudgetCycle`	str \| None
`defaultMemberRpmLimit`	int \| None
`defaultMemberTpmLimit`	int \| None
`memberKeyDurationDays`	int \| None
`fallbacksEnabled`	bool
`updatedAt`	str

WorkspaceMembers¶

Field	Type	Meaning
`items`	list[WorkspaceMember]
`total`	int

WorkspaceMember¶

Field	Type	Meaning
`id`	str
`name`	str
`email`	str
`role`	str
`joinedAt`	str
`lastActiveAt`	str \| None
`keyCount`	int
`currentSpend`	float
`maxBudgetUncapped`	bool

WorkspaceBudget¶

Field	Type	Meaning
`budget`	float \| None
`budgetCycle`	str
`spend`	float

Detectors, guardrails & policies¶

Detector¶

Field	Type	Meaning
`uuid`	str
`detectorType`	str	`regex`, `managed` (DLP) or `ai` (Natural Language).
`approvalStatus`	str	`draft`, `pending`, `active` or `rejected`.
`inputGuards`	list[str]
`outputGuards`	list[str]
`ruleCount`	int
`sensitivity`	Any
`engine`	str	`CPU` or `GPU`.
`managedEngine`	str \| None
`action`	str \| None
`rules`	list[DetectorRule]
`regexRules`	list[RuleGroup] \| None
`aiRules`	list[RuleGroup] \| None
`name`	str
`description`	str
`ownerWorkspaceId`	str \| None
`scope`	str	`workspace` or `org`.
`submittedBy`	UserRef \| None
`submittedAt`	str \| None
`rejectionReason`	str \| None
`createdAt`	str
`updatedAt`	str
`activatedAt`	str \| None
`contentUpdatedAt`	str \| None
`hasPendingChange`	bool	An edit is waiting for approval; the active version still applies.
`pendingDeletion`	bool
`pendingChangeKind`	str \| None

DetectorRule¶

One entry of a detector's flat rules list, the one the engine evaluates. Which fields are set depends on the detector type.

Field	Type	Meaning
`id`	str
`pattern`	str	Regex detectors.
`description`	str	Natural Language detectors: the plain-language condition.
`category`	str	DLP detectors: the DLP label.
`disposition`	str	`block`, `redact`, `log`, ...
`threshold`	float
`replacement`	str

RuleGroup¶

An entry of regexRules / aiRules (the editor's grouping), or a built-in detector's rule.

Field	Type	Meaning
`id`	str
`name`	str
`description`	str
`enabled`	bool
`conditions`	list[DetectorRule]
`violateIf`	list[str]
`exemptIf`	list[str]

BuiltinDetector¶

Field	Type	Meaning
`id`	str	A slug (`owasp-llm-top-10-2025`), usable wherever a detector id is.
`name`	str
`description`	str
`category`	str
`group`	str
`engine`	str
`action`	str
`rules`	list[RuleGroup]

Guardrail¶

Field	Type	Meaning
`id`	str
`status`	str	`draft`, `pending`, `active` or `rejected`.
`detectorIds`	list[str]
`denySuspiciousCharacters`	bool
`usedByPolicyCount`	int
`name`	str
`description`	str
`ownerWorkspaceId`	str \| None
`scope`	str	`workspace` or `org`.
`submittedBy`	UserRef \| None
`submittedAt`	str \| None
`rejectionReason`	str \| None
`createdAt`	str
`updatedAt`	str
`activatedAt`	str \| None
`contentUpdatedAt`	str \| None
`hasPendingChange`	bool	An edit is waiting for approval; the active version still applies.
`pendingDeletion`	bool
`pendingChangeKind`	str \| None

Policy¶

Field	Type	Meaning
`id`	str
`status`	str	`draft`, `pending`, `active` or `rejected`.
`inputGuardrailIds`	list[str]
`outputGuardrailIds`	list[str]
`responseScanMode`	str	`post_stream` or `in_stream`.
`providerAccess`	list[ProviderAccess]
`assignedWorkspaceIds`	list[str]
`applyToOrganization`	bool
`name`	str
`description`	str
`ownerWorkspaceId`	str \| None
`scope`	str	`workspace` or `org`.
`submittedBy`	UserRef \| None
`submittedAt`	str \| None
`rejectionReason`	str \| None
`createdAt`	str
`updatedAt`	str
`activatedAt`	str \| None
`contentUpdatedAt`	str \| None
`hasPendingChange`	bool	An edit is waiting for approval; the active version still applies.
`pendingDeletion`	bool
`pendingChangeKind`	str \| None

ReviewItem¶

An object waiting in the org admin's review queue.

Field	Type	Meaning
`id`	str
`name`	str
`type`	str	`detector`, `guardrail` or `policy` (see `QUEUE_KIND`).
`changeKind`	str	`create`, `update` or `delete`.
`ownerWorkspaceId`	str
`submittedBy`	UserRef
`submittedAt`	str
`updatedAt`	str

DetectorTest¶

A detector scan result.

Field	Type	Meaning
`matched`	bool
`finalDisposition`	str \| None	What would happen: `block`, `redact`, ... or None.
`score`	float
`details`	str	Human-readable, e.g. `Matched rules: ssn (block)`.
`spans`	list[Span]
`rewritten`	str \| None	The redacted text, for a redacting detector.
`latencyMs`	int
`scannedChars`	int
`truncated`	bool
`checkedLocally`	bool	True when `playground` matched a regex body locally (no server endpoint).

GuardrailTest¶

A guardrail scan result: the overall outcome and one row per detector.

Field	Type	Meaning
`finalDisposition`	str \| None
`results`	list[GuardrailTestResult]
`suspiciousCharacters`	Any
`decoding`	Any
`rewritten`	str \| None
`latencyMs`	int
`scannedChars`	int
`truncated`	bool

GuardrailTestResult¶

Field	Type	Meaning
`detectorId`	str
`status`	str	`untested` for a built-in detector a build cannot test offline.
`matched`	bool
`finalDisposition`	str \| None
`score`	float
`details`	str
`spans`	list[Span]

Span¶

A matched character range in scanned text.

Field	Type	Meaning
`start`	int
`end`	int

Virtual keys¶

VirtualKey¶

Field	Type	Meaning
`id`	str
`keyName`	str
`keyType`	str	`user` or `service`.
`scope`	str
`keyPreview`	str	`faig_…6b0b`: enough to recognise, never the secret.
`status`	str	`active`, `revoked`, ...
`createdBy`	UserRef
`owner`	UserRef \| None
`workspace`	IdName
`project`	IdName \| None
`policyIds`	list[PolicyAssignment]
`providerAccess`	list[ProviderAccess]
`modelGroups`	list[ModelGroup]
`budgetWindows`	BudgetWindows	Spend caps per window (None = uncapped).
`windowSpend`	BudgetWindows	Spend so far in each window.
`workspaceSpend`	float
`suspension`	Any
`hiddenByProject`	bool
`spend`	float
`tpm`	int \| None
`rpm`	int \| None
`expiresAt`	str \| None
`lastUsedAt`	str \| None
`revokedAt`	str \| None
`revokeReason`	str \| None
`createdAt`	str
`updatedAt`	str
`updatedBy`	UserRef

NewVirtualKey¶

A key as create and rotate return it: the record plus its secret.

Everything in VirtualKey, plus the fields below marked new.

Field	Type	Meaning
`secretKey` (new)	str	The `faig_...` secret. Shown ONCE; store it now.
`previousSecretValidUntil` (new)	str \| None	After a rotate, until when the old secret still works (None: not at all).
`id`	str
`keyName`	str
`keyType`	str	`user` or `service`.
`scope`	str
`keyPreview`	str	`faig_…6b0b`: enough to recognise, never the secret.
`status`	str	`active`, `revoked`, ...
`createdBy`	UserRef
`owner`	UserRef \| None
`workspace`	IdName
`project`	IdName \| None
`policyIds`	list[PolicyAssignment]
`providerAccess`	list[ProviderAccess]
`modelGroups`	list[ModelGroup]
`budgetWindows`	BudgetWindows	Spend caps per window (None = uncapped).
`windowSpend`	BudgetWindows	Spend so far in each window.
`workspaceSpend`	float
`suspension`	Any
`hiddenByProject`	bool
`spend`	float
`tpm`	int \| None
`rpm`	int \| None
`expiresAt`	str \| None
`lastUsedAt`	str \| None
`revokedAt`	str \| None
`revokeReason`	str \| None
`createdAt`	str
`updatedAt`	str
`updatedBy`	UserRef

PolicyAssignment¶

Field	Type	Meaning
`id`	str
`assignedByOrg`	bool	Forced onto the key by the org; cannot be removed from the key.

BudgetWindows¶

Field	Type	Meaning
`hourly`	float \| None
`daily`	float \| None
`weekly`	float \| None
`monthly`	float \| None

KeyCheck¶

Field	Type	Meaning
`valid`	bool
`model_count`	int
`http_status`	int

Models & providers¶

Model¶

A model the org knows. Costs are per million tokens.

Field	Type	Meaning
`uuid`	str
`publicName`	str
`modelId`	str
`providerId`	str
`platform`	str
`label`	str
`isCustom`	bool
`customizedCost`	bool
`healthStatus`	str	`healthy`, `unhealthy`, `unknown`.
`healthSource`	str \| None
`lastCheckedAt`	str \| None
`healthExpiresAt`	str \| None
`lastActivityAt`	str \| None
`baseInputCost`	float
`baseOutputCost`	float \| None
`baseCacheReadCost`	float \| None
`baseCacheWriteCost`	float \| None
`effectiveInputCost`	float
`effectiveOutputCost`	float \| None
`effectiveCacheReadCost`	float \| None
`effectiveCacheWriteCost`	float \| None
`requestFee`	float \| None

AiProvider¶

Field	Type	Meaning
`providerId`	str
`label`	str
`platform`	str	`openai`, `anthropic`, `custom`, ...
`baseUrl`	str
`description`	str \| None
`modelCount`	int
`enabledModelCount`	int
`keyCount`	int

ProviderAccess¶

Which of a provider's models (and upstream keys) are granted.

Field	Type	Meaning
`providerId`	str
`name`	str
`platform`	str
`allModels`	bool
`allKeys`	bool
`workspaceDefaultKeys`	bool
`blockedModelUuids`	list[str]
`excludedKeyIds`	list[str]
`keys`	list[ProviderKey]
`models`	list[ModelGrant]

ModelGrant¶

One model inside a provider grant.

Field	Type	Meaning
`uuid`	str
`modelId`	str	The provider's model id (`gpt-4o-2024-08-06`).
`publicName`	str	The name callers use on the gateway (`openai-gpt-4o-2024-08-06`).
`enabled`	bool
`workspaceEnabled`	bool	Workspace `grantable_providers` only, as are the fields below.
`effectiveEnabled`	bool	Usable: enabled for the org AND the workspace.
`grantedViaGroups`	list[Any]
`effectiveInputCost`	float
`effectiveOutputCost`	float \| None
`effectiveCacheReadCost`	float \| None
`effectiveCacheWriteCost`	float \| None
`requestFee`	float \| None
`healthStatus`	str
`healthSource`	str \| None
`lastCheckedAt`	str \| None
`healthExpiresAt`	str \| None
`lastActivityAt`	str \| None

ProviderKey¶

An upstream provider credential (its name, never its secret).

Field	Type	Meaning
`id`	str
`name`	str
`description`	str \| None
`enabled`	bool

ModelGroup¶

A named set of models with a routing strategy (random, ...).

Field	Type	Meaning
`id`	str
`name`	str
`description`	str \| None
`strategy`	str
`members`	list[ModelGroupMember]
`memberCount`	int	Workspace path only.
`usableMemberCount`	int	Workspace path only.
`grantedTo`	list[dict[str, Any]]	`[{"workspaceId", "workspaceName"}]` (org path only).
`createdAt`	str
`createdBy`	str
`updatedAt`	str
`updatedBy`	str \| None

ModelGroupMember¶

Field	Type	Meaning
`model`	dict[str, Any]	`{"uuid", "modelId", "providerId", "publicName"}`.
`status`	str
`usability`	str	Workspace path only: `usable` when the workspace can route to it.
`priority`	int \| None
`weight`	int \| None

GrantableProvider¶

A provider whose models and keys can be granted.

Field	Type	Meaning
`providerId`	str
`name`	str
`platform`	str
`autoSyncNewModels`	bool
`keys`	list[ProviderKey]
`models`	list[ModelGrant]
`defaultKeyIds`	list[str]	Workspace path only.
`groupReachedModels`	list[Any]	Workspace path only.

DlpLabel¶

Field	Type	Meaning
`category`	str	The name `dlp_detector_body` takes (`Account number`, ...).
`defaultAction`	str
`defaultReplacement`	str
`defaultThreshold`	float
`sample`	str

Licenses¶

Field	Type	Meaning
`scanningEnabled`	bool
`licenses`	list[License]
`mapping`	list[dict[str, Any]]	`[{"serialNumber", "gpu": {"id", "product"}}]`.

License¶

Field	Type	Meaning
`serialNumber`	str
`status`	str
`endDate`	str
`nodeName`	str

Usage & cost reports¶

UsageSummary¶

Field	Type	Meaning
`window`	DateWindow
`previousWindow`	DateWindow	The same-length window before, for comparison.
`totals`	Volume
`adoption`	UsageAdoption

UsageAdoption¶

Field	Type	Meaning
`activeUsers`	int
`provisionedUsers`	int
`activeKeys`	int
`provisionedKeys`	int

UsageTrend¶

Field	Type	Meaning
`interval`	str
`points`	list[UsageTrendPoint]

UsageTrendPoint¶

Field	Type	Meaning
`at`	str
`requests`	int
`tokens`	int
`partial`	bool	The bucket is still filling (it includes now).

CostSummary¶

Field	Type	Meaning
`window`	DateWindow
`previousWindow`	DateWindow
`measures`	list[str]	The spend measures present, e.g. `["chargebackSpend"]`.
`totals`	CostTotals
`volume`	Volume

CostTotals¶

Field	Type	Meaning
`chargebackSpend`	Spend
`providerSpend`	Spend

CostTrend¶

Field	Type	Meaning
`interval`	str
`measures`	list[str]
`points`	list[CostTrendPoint]

CostTrendPoint¶

Field	Type	Meaning
`at`	str
`chargebackSpend`	float
`providerSpend`	float
`partial`	bool

Rankings¶

Read the rows with rank_items(): items, or top/bottom for end="both", and only meta when nothing was used.

Field	Type	Meaning
`items`	list[RankRow]
`top`	list[RankRow]
`bottom`	list[RankRow]
`measures`	list[str]
`meta`	RankMeta

RankRow¶

One ranked key, user, workspace or model. Usage rankings carry requests/tokens; cost rankings chargebackSpend, share and volume.

Field	Type	Meaning
`id`	str
`name`	str	For a deleted key, its id.
`slot`	int
`deleted`	bool
`status`	str
`keyType`	str
`requests`	int
`tokens`	int
`chargebackSpend`	Spend
`providerSpend`	Spend
`share`	float	Fraction (0-1) of the window's spend.
`volume`	Volume
`scope`	ScopeRef
`scopes`	list[ScopeRef]
`owner`	UserRef
`user`	UserRef
`role`	str
`provider`	IdName

RankMeta¶

Field	Type	Meaning
`totalCount`	int	How many items exist in the dimension, not how many were returned.
`complete`	bool
`windowRequests`	int
`windowTokens`	int
`dimensionRequests`	int
`dimensionTokens`	int
`windowTotals`	CostTotals

Breakdown¶

Read the rows with breakdown_items(). A key, user or workspace splits into models (a user or workspace may add keys); a model into consumers (usage) or spenders (cost).

Field	Type	Meaning
`models`	BreakdownGroup
`keys`	BreakdownGroup
`consumers`	BreakdownGroup
`spenders`	BreakdownGroup
`total`	BreakdownTotal
`measures`	list[str]

BreakdownGroup¶

Field	Type	Meaning
`count`	int
`items`	list[BreakdownRow]
`attributed`	Volume

BreakdownRow¶

Field	Type	Meaning
`id`	str
`name`	str
`kind`	str	For consumers/spenders: `user`, `service_key`, ...
`status`	str
`requests`	int
`tokens`	int
`chargebackSpend`	Spend
`provider`	IdName

BreakdownTotal¶

Field	Type	Meaning
`requests`	int
`tokens`	int
`chargebackSpend`	Spend

Spend¶

Field	Type	Meaning
`amount`	float	Total spend in the window.
`perRequest`	float
`per1kTokens`	float \| None

Volume¶

Field	Type	Meaning
`requests`	int
`tokens`	int

DateWindow¶

A report window: {"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}.

Field	Type	Meaning
`from`	str
`to`	str

Analytics¶

Guardrail analytics for a window.

Field	Type	Meaning
`window`	DateWindow
`timeRange`	str
`scope`	dict[str, Any]	`{"workspace": DisplayRef \\| None}`.
`summary`	AnalyticsSummary
`violations`	Violations
`detectors`	dict[str, Any]	`{"items": [DetectorTriggers]}`.
`governancePacks`	dict[str, Any]	`{"catalogCount", "items": [{"pack": DisplayRef, "triggers"}]}`.
`violationTrend`	dict[str, Any]	`{"bucketUnit", "bucketMinutes", "buckets": [Outcomes + "startsAt"]}`.
`scannerLatency`	dict[str, Any]	`{"points": [{"at", "avgMs", "p50Ms", "p95Ms", "p99Ms"}], "summaries": [...]}`.
`unhandled`	dict[str, Any]	`{"cells": [{"severity", "handled", "total", "detectors"}]}`.

AnalyticsSummary¶

Field	Type	Meaning
`totalScanned`	int
`cleanRequests`	int
`violatedRequests`	int
`unscanned`	int
`outcomes`	Outcomes
`severity`	dict[str, int]	`{"critical", "high", "medium", "low"}` counts.
`criticalByOutcome`	Outcomes
`highByOutcome`	Outcomes
`latency`	dict[str, int]	`{"avgMs", "guardOverheadMs"}`.
`deltas`	dict[str, Any]	Change against the previous window, per measure: `{"abs", "pct"}`.
`unboundModels`	list[Any]

Outcomes¶

Field	Type	Meaning
`blocked`	int
`redacted`	int
`alerted`	int
`logged`	int

Violations¶

Field	Type	Meaning
`limit`	int
`byKey`	list[ViolationRow]
`byUser`	list[ViolationRow]
`byWorkspace`	list[ViolationRow] \| None	None on the workspace path.

ViolationRow¶

Field	Type	Meaning
`entity`	DisplayRef	The key, user or workspace.
`requests`	int
`violations`	int
`previousViolations`	int \| None
`criticalUnhandled`	int
`deleted`	bool
`guardrails`	list[dict[str, Any]]	`[{"guardrail": {"id", "displayName"}, "hits"}]`.
`keyStatus`	str \| None
`keyType`	str \| None
`owner`	Any
`workspace`	DisplayRef \| None

DetectorTriggers¶

Field	Type	Meaning
`detector`	DisplayRef
`triggers`	int
`disposition`	str
`criticalUnhandled`	int
`owner`	Any
`submittedBy`	Any

Traffic, audit & ICAP logs¶

TrafficLogPage¶

Field	Type	Meaning
`items`	list[TrafficLogRow]
`total`	int	On the first page only.
`offset`	int
`hasNext`	bool
`hasPrev`	bool
`nextCursor`	str \| None	Pass back as `cursor` for the next page.
`prevCursor`	str \| None

TrafficLogRow¶

A row of traffic_logs.

Field	Type	Meaning
`uuid`	str
`timeStamp`	int	Epoch milliseconds.
`verdict`	bool	True when a guardrail acted (see `verdictLabel`).
`verdictLabel`	str	`Block` or `Log`.
`action`	str	`DENY` for a block, else empty.
`status`	str	`success` or `failure` (the request itself, e.g. a 429).
`user`	str
`workspace`	str
`isGlobalKey`	bool
`keyAlias`	str	The key's NAME (what the `virtual_key` filter matches).
`keyPrefix`	str
`keyType`	str
`model`	str \| None
`modelGroup`	str \| None
`requestPath`	str
`trafficType`	str	`Governed` or `Passthrough`.

TrafficLog¶

The full record from traffic_log(uuid). On 8.0.2 detector, guardrail and policy are empty: the detectors that matched are in violation (detectorName, details).

Everything in TrafficLogRow, plus the fields below marked new.

Field	Type	Meaning
`httpStatus` (new)	int
`errorCode` (new)	str \| None	e.g. `rate_limit_exceeded`.
`upstreamMessage` (new)	str \| None
`outcome` (new)	str \| None
`costBasis` (new)	str
`cost` (new)	str
`duration` (new)	str \| None
`latency` (new)	Any
`aiFlow` (new)	Any
`guardName` (new)	str \| None
`guardType` (new)	str	`input` or `output`: which side was scanned (or blocked).
`detector` (new)	str \| None
`guardrail` (new)	str \| None
`policy` (new)	str \| None
`ipaddress` (new)	list[str]
`prompt` (new)	PromptText
`response` (new)	PromptText
`systemPrompt` (new)	str
`tokens` (new)	dict[str, int]	`{"input", "output"}`.
`toolCalls` (new)	list[Any]
`toolDefinitions` (new)	list[Any]
`toolResponses` (new)	list[Any]
`violation` (new)	dict[str, list[Any]]	`{"input": [...], "output": [...]}`: what each side matched.
`userAgent` (new)	str \| None
`requestId` (new)	str
`sessionId` (new)	str \| None
`org` (new)	Any
`uuid`	str
`timeStamp`	int	Epoch milliseconds.
`verdict`	bool	True when a guardrail acted (see `verdictLabel`).
`verdictLabel`	str	`Block` or `Log`.
`action`	str	`DENY` for a block, else empty.
`status`	str	`success` or `failure` (the request itself, e.g. a 429).
`user`	str
`workspace`	str
`isGlobalKey`	bool
`keyAlias`	str	The key's NAME (what the `virtual_key` filter matches).
`keyPrefix`	str
`keyType`	str
`model`	str \| None
`modelGroup`	str \| None
`requestPath`	str
`trafficType`	str	`Governed` or `Passthrough`.

BlockedRequest¶

One blocked request from blocked_requests(): the traffic log joined with the virtual key that sent it, flat enough to map onto a SOAR alert.

Field	Type	Meaning
`uuid`	str	The traffic log's id: stable, use it to de-duplicate.
`time`	str	ISO 8601, UTC.
`timeStamp`	int	Epoch milliseconds.
`workspace`	str
`user`	str
`model`	str
`requestPath`	str
`action`	str
`prompt`	str
`response`	str
`detectors`	list[BlockedDetector]
`reason`	str	The first detector's `details`.
`keyName`	str
`keyPrefix`	str
`keyId`	str \| None	None when the key is gone or its name is ambiguous.
`keyStatus`	str \| None
`ownerName`	str \| None
`ownerEmail`	str \| None

BlockedDetector¶

Field	Type	Meaning
`name`	str
`type`	str	`REGEX`, `NL`, `DLP`, a built-in's type, ...
`details`	str	Why it fired, e.g. `Matched rules: launch-code (block)`.
`side`	str	`input` (the prompt) or `output` (the model's answer).
`id`	str

PromptText¶

Field	Type	Meaning
`original`	str
`modified`	str \| None	The text after redaction, when a detector rewrote it.

TrafficFilterOptions¶

The values seen in the window, per filter (virtualKey = key names).

Field	Type	Meaning
`verdict`	list[str]
`user`	list[str]
`workspace`	list[str]
`virtualKey`	list[str]
`model`	list[str]
`trafficType`	list[str]

AuditLogPage¶

Field	Type	Meaning
`items`	list[AuditLogRow]
`total`	int	On the first page only.
`offset`	int
`hasNext`	bool
`hasPrev`	bool
`nextCursor`	str \| None	Pass back as `cursor` for the next page.
`prevCursor`	str \| None

AuditLogRow¶

Field	Type	Meaning
`uuid`	str
`timeStamp`	int	Epoch milliseconds.
`username`	str
`sourceIp`	str
`type`	str	`Configuration`, `Authentication`, ...
`action`	str	Lowercase (`create`); filter values are capitalised (`Create`).
`actionLabel`	str
`message`	str
`role`	str
`workspace`	str \| None

AuditFilterOptions¶

Field	Type	Meaning
`user`	list[str]
`role`	list[str]
`action`	list[str]
`workspace`	list[str]

IcapLogPage¶

Not verified live (ICAP was off on the test appliance); rows untyped.

Field	Type	Meaning
`items`	list[dict[str, Any]]
`total`	int	On the first page only.
`offset`	int
`hasNext`	bool
`hasPrev`	bool
`nextCursor`	str \| None	Pass back as `cursor` for the next page.
`prevCursor`	str \| None

Gateway¶

ChatCompletion¶

An OpenAI-compatible chat completion.

Field	Type	Meaning
`id`	str
`object`	str
`created`	int
`model`	str
`choices`	list[ChatChoice]
`usage`	ChatUsage
`service_tier`	str
`system_fingerprint`	str

ChatChoice¶

Field	Type	Meaning
`index`	int
`message`	ChatMessage
`finish_reason`	str \| None	`content_filter` when a guardrail blocked (see `blocked`).
`logprobs`	Any

ChatMessage¶

Field	Type	Meaning
`role`	str
`content`	str \| None

ChatUsage¶

Field	Type	Meaning
`prompt_tokens`	int
`completion_tokens`	int
`total_tokens`	int
`prompt_tokens_details`	dict[str, Any]
`completion_tokens_details`	dict[str, Any]

ChatCompletionChunk¶

One streamed chat.completion.chunk.

Field	Type	Meaning
`id`	str
`object`	str
`created`	int
`model`	str
`choices`	list[ChunkChoice]
`usage`	ChatUsage
`service_tier`	str
`system_fingerprint`	str

ChunkChoice¶

Field	Type	Meaning
`index`	int
`delta`	ChatMessage
`finish_reason`	str \| None
`logprobs`	Any

Shared¶

IdName¶

Field	Type	Meaning
`id`	str
`name`	str

DisplayRef¶

A reference to another object, as analytics and rankings give it.

Field	Type	Meaning
`id`	str
`displayName`	str

ScopeRef¶

Field	Type	Meaning
`kind`	str	`workspace` (the only kind seen on 8.0.2).
`id`	str
`displayName`	str

UserRef¶

Field	Type	Meaning
`id`	str
`email`	str
`fullName`	str \| None