Skip to content

admin

Admin API models for user management and platform statistics.

AdminAnalysisConfigOut pydantic-model

Bases: BaseModel

An analysis in the registry, and who it is offered to.

Fields:

origin pydantic-field

Who developed it, as its provenance declares.

owner_org_id = None pydantic-field

The organization whose members see and run it while it is private.

promoted_at = None pydantic-field

When it was published; null if it never was.

promotion_refused = None pydantic-field

Why a promotion would be refused now; null when it would be accepted.

AdminAnalysisConfigUpdate pydantic-model

Bases: BaseModel

Change who an analysis is offered to. Omitted fields stay as they are.

visibility moves an analysis one way: private to public is a promotion, and either to withdrawn is a withdrawal. Nothing returns to private; a changed analysis is registered as a new version.

Fields:

owner_org_id = None pydantic-field

The organization that may see and run it while it is private; an explicit null removes the owner.

visibility = None pydantic-field

public to promote, withdrawn to withdraw.

AdminAnalysisListResponse pydantic-model

Bases: PaginatedResponse

A page of analyses across accounts, newest first.

Fields:

AdminAnalysisOut pydantic-model

Bases: AnalysisIdMixin, AnalysisStatusMixin, AnalysisTimingMixin

An analysis as an administrator operates on it.

Its status, timing, owner, cost and outcome, and the ids of what it ran on. Never the names people gave their projects, studies or files, which operating the platform does not need.

Config:

  • from_attributes: True

Fields:

analysis_config_id pydantic-field

ID of the analysis configuration used for the analysis.

analysis_config_name pydantic-field

Name of the analysis configuration used for the analysis.

analysis_hours pydantic-field

Signal hours the analysis was priced on.

cost pydantic-field

Credits charged for the analysis, or held while it is live.

deleted_at = None pydantic-field

When the analysis was deleted, for listings that include deleted rows. Null for live analyses.

exit_code = None pydantic-field

Exit code of the analysis process, once it has run.

org_id = None pydantic-field

The owning organization. Null when it was erased.

project_id = None pydantic-field

ID of the project the analysis belongs to. None if deleted.

recording_id = None pydantic-field

ID of the recording the analysis ran on. None if deleted.

user_email = None pydantic-field

The owning account's email. Null when that account was erased.

user_id = None pydantic-field

The owning account. Null when that account was erased.

AdminCancelAnalysesRequest pydantic-model

Bases: BaseModel

Cancel analyses across accounts.

Addresses its subjects with a selector. Only live, not-yet-settled analyses are cancelled; a finished one addressed by id is reported as an error, and a filter never resolves to one.

Fields:

Validators:

  • _guard

expected_count = None pydantic-field

Required for live-set selectors (filter/all): the resolved count the caller saw on the admin analysis list. The server re-resolves and rejects on a mismatch.

AdminCancelAnalysesResponse pydantic-model

Bases: BaseModel

Outcome of one page of an admin cancellation.

Fields:

AdminCancelSummary pydantic-model

Bases: BatchCancelSummary

Counts for one page of an admin cancellation.

Fields:

  • total (int)
  • cancelled (int)
  • errors (int)
  • remaining (int)

remaining pydantic-field

Live analyses the selector still addresses after this page. Call again with the same selector until this is zero; each call handles at most the server's per-request cap.

AdminCapabilityRequestDecline pydantic-model

Bases: BaseModel

Decline a request for a capability, with the reason the organisation is shown.

Fields:

  • reason (str)

AdminCapabilityRequestOut pydantic-model

Bases: CapabilityRequestOut

A request for a capability as administrators see it: with its organisation.

Fields:

AdminCapabilityRequestPage pydantic-model

Bases: BaseModel

One page of requests for capabilities across organisations, pending first, oldest first.

Config:

  • frozen: True

Fields:

AdminCreditRequestApprove pydantic-model

Bases: BaseModel

Approve a grant or extension request, as asked or with changes.

Fields:

amount = None pydantic-field

Credits to grant; null grants the amount requested. Ignored for an extension.

note = None pydantic-field

Recorded with the decision for administrators; never sent.

term_months = None pydantic-field

The term to grant or extend by; null keeps the requested one.

AdminCreditRequestDecline pydantic-model

Bases: BaseModel

Decline a grant or extension request, with a reason the requester is sent.

Fields:

note = None pydantic-field

Recorded with the decision for administrators; never sent.

notify = True pydantic-field

Email the requester the decision and its reason.

AdminCreditRequestOut pydantic-model

Bases: CreditRequestOut

A request as administrators see it: with its organization and the decision's note.

Fields:

AdminCreditRequestPage pydantic-model

Bases: BaseModel

One page of requests across organizations, pending first, oldest first.

Config:

  • frozen: True

Fields:

AdminEntitlementChange pydantic-model

Bases: BaseModel

Turn one of an organisation's capabilities on or off.

On needs the owner's acceptance of the latest published site agreement, unless the platform operates the organisation itself. Off is always allowed; it stops new work at the organisation's site, and nothing already there is touched.

Fields:

reason pydantic-field

Why, for the organisation's audit trail and the administrators.

AdminGrantCreate pydantic-model

Bases: BaseModel

Research credits an administrator grants an organization directly.

Fields:

amount pydantic-field

Credits to grant.

reason pydantic-field

Why the credits are granted (kept with the grant).

term_months = None pydantic-field

How long the grant lasts, from the offered terms; null for a grant that never expires.

AdminHealthDetail pydantic-model

Bases: BaseModel

The API's health, dependency by dependency.

The public health endpoint reports only the overall status. This breakdown is for operators. It is always returned with 200; the status fields carry the diagnosis.

Fields:

  • status (Literal['ok', 'degraded', 'unhealthy'])
  • postgres (Literal['ok', 'error'])
  • redis (Literal['ok', 'error'])
  • runners (Literal['ok', 'none seen'])

postgres pydantic-field

Whether the database answers a trivial query in time.

redis pydantic-field

Whether Redis answers a ping in time.

runners pydantic-field

Whether an approved runner has asked for work in the last few minutes.

status pydantic-field

ok when every dependency answers and a runner has been seen recently; degraded when no runner has, so analyses wait but everything else works; unhealthy when the database or Redis does not answer.

AdminOrganizationDetailOut pydantic-model

Bases: AdminOrganizationOut

One organization with its members, as the operators see it.

Fields:

capabilities = None pydantic-field

Its capabilities on its own hardware, and the site agreement they rest on.

members pydantic-field

Every member, owner first.

AdminOrganizationListResponse pydantic-model

Bases: PaginatedResponse

Paginated organization list response.

Fields:

AdminOrganizationOut pydantic-model

Bases: BaseModel

An organization as the operators list it.

Identity, owner, seats, projects, storage and credits in one row, with the overrides an administrator may set and the values actually in force. Retired organizations (deleted_at set) are listed only on request.

Config:

  • from_attributes: True

Fields:

analyses_at_site = False pydantic-field

Whether the organisation's analyses run at its site.

credits pydantic-field

The organization's credit balance.

deleted_at = None pydantic-field

When the organization was retired, if it was.

effective_project_limit = None pydantic-field

The projects the organization may hold — the override, else the configured default; null when uncapped.

effective_seat_limit = None pydantic-field

The seat limit in force — the override, else the configured default; null when uncapped.

effective_site_compute_factor = 0 pydantic-field

The factor in force on the platform price for analyses run at the organisation's site: the override, else the platform's.

effective_storage_ceiling_gb = 0 pydantic-field

The storage ceiling in force (GB).

effective_study_limit = None pydantic-field

The studies one project may hold — the override, else the configured default, never above the platform's ceiling.

owner_user_id = None pydantic-field

The owner's user id (every live organization has one).

pending_invitation_count = 0 pydantic-field

Invitations sent and not yet accepted, revoked or expired.

platform_operated = False pydantic-field

Whether the platform operates the organisation itself.

project_limit = None pydantic-field

The project-limit override, if set.

recordings_at_site = False pydantic-field

Whether the organisation's new projects keep their recordings in its bucket.

seat_limit = None pydantic-field

The seat-limit override, if set.

site_compute_factor = None pydantic-field

The site-compute factor override, if set.

storage_bytes = 0 pydantic-field

Bytes held against the organization's storage ceiling.

storage_ceiling_gb = None pydantic-field

The storage-ceiling override (GB), if set.

storage_insolvent_since = None pydantic-field

When the balance stopped covering the storage debit; null = solvent.

study_limit = None pydantic-field

The per-project study-limit override, if set.

AdminOrganizationUpdate pydantic-model

Bases: BaseModel

An administrator's change to an organization's limits and settings.

Each limit, and the site-compute factor, is an override of the platform's configured default: a value sets it, an explicit null clears it (back to the default), and an omitted field is left unchanged. Servers distinguish the last two through model_fields_set. An unknown field is refused, not ignored.

Config:

  • extra: forbid

Fields:

Validators:

  • _switches_are_set_or_left

analyses_at_site = None pydantic-field

Whether the organisation's analyses run at its site. Turning it on needs site compute and an approved runner of the organisation's site pool taking work. It takes effect at the next submission; an analysis already queued stays where it is. It cannot be cleared to null.

platform_operated = None pydantic-field

Whether the platform operates the organisation itself, as for a demonstration site. Such an organisation's capabilities are turned on without an acceptance of the site agreement. It cannot be cleared to null.

project_limit = None pydantic-field

Projects the organization may hold.

recordings_at_site = None pydantic-field

Whether the organisation's new projects keep their recordings in its registered bucket. Turning it on needs site storage, analyses at the site, and a bucket whose browser check passed with its current key. Existing projects keep where they are stored. It cannot be cleared to null.

seat_limit = None pydantic-field

Members plus pending invitations the organization may hold.

site_compute_factor = None pydantic-field

The organisation's own factor on the platform price for analyses run at its site, as its agreement sets it. Null clears it back to the platform's factor.

storage_ceiling_gb = None pydantic-field

The storage the organization may use (GB).

study_limit = None pydantic-field

Studies one of the organization's projects may hold, at most the platform's ceiling.

AdminPendingInvitation pydantic-model

Bases: BaseModel

An open invitation addressed to an account's email, as the admin views show it.

Tells an administrator reviewing an applicant who asked them to join, and into which organization, before the account is approved.

Config:

  • frozen: True

Fields:

created_at pydantic-field

When it was sent.

expires_at pydantic-field

When it stops being acceptable.

id pydantic-field

Unique identifier of the invitation.

invited_by_email = None pydantic-field

Email of the member who sent it; null when that account was deleted.

invited_by_id = None pydantic-field

The member who sent it; null when that account was deleted.

invited_by_name = None pydantic-field

Display name of the member who sent it, if set.

organization_id pydantic-field

The organization that sent it.

organization_name pydantic-field

The organization's display name.

role pydantic-field

The role the invitee would join with.

AdminQueueSummary pydantic-model

Bases: BaseModel

The queue in one read.

What is live, how long the oldest has waited, and who holds it.

Fields:

by_status pydantic-field

Live analyses by status; statuses with none are absent.

oldest_waiting_seconds = None pydantic-field

Age of the oldest analysis still waiting to run (pending or enqueued), or null when nothing waits.

per_user pydantic-field

Accounts holding live analyses, most first, capped by the server.

sampled_at pydantic-field

When this summary was read.

AdminQueueUserShare pydantic-model

Bases: BaseModel

One account's share of the live analyses.

Fields:

active pydantic-field

Live, not-yet-settled analyses.

user_email = None pydantic-field

Null when the account was erased while its analyses were still live.

AdminUserCreate pydantic-model

Bases: BaseModel

Admin user creation request.

Fields:

Validators:

  • _require_password_unless_generated

confirm_email = True pydantic-field

Whether to pre-confirm the user's email address.

credits = 0 pydantic-field

Research credits granted to the new account's organization on top of its starter grant; they never expire.

email pydantic-field

Email address for the new user.

generate_password = False pydantic-field

If true, ignore password, generate a strong random password, and email the user a one-time link to set their own password. The email is always pre-confirmed in this mode so the setup link can be delivered.

name = None pydantic-field

The new user's name. Defaults to the email local-part if omitted (admin-provisioned accounts are not request-access applicants).

organization = None pydantic-field

Organization the user belongs to.

password = None pydantic-field

Password for the new user. Required unless generate_password is set, in which case any supplied value is ignored.

permissions = None pydantic-field

Permissions for the new user. None uses config defaults.

position = None pydantic-field

Position of the user in their organization.

role = Role.USER pydantic-field

Authorization role for the new user (user or admin).

AdminUserListResponse pydantic-model

Bases: PaginatedResponse

Paginated user list response.

Fields:

AdminUserOut pydantic-model

Bases: UserOut

An account as the operators see it.

The account's own settings and state. What belongs to its organization (limits, overrides, the credit balance) is read and set on the organization: :class:AdminOrganizationOut.

Config:

  • from_attributes: True

Fields:

can_create_api_keys pydantic-field

Whether the account may create API keys — it holds the api-key-create permission. Granted by an administrator; server-derived from the permission set, never stored separately.

can_submit pydantic-field

Whether the account may submit analyses — it holds the analysis-create permission, directly or through the wildcard. Server-derived from the permission set, never stored separately.

can_upload pydantic-field

Whether the account may register recordings — it holds the recording-create permission, directly or through the wildcard. Server-derived from the permission set, never stored separately.

pending_invitations pydantic-field

Open invitations addressed to the account's email: not accepted, not revoked, not expired, from an organization that still exists. Shows who invited an applicant awaiting approval, and where to.

AdminUserReject pydantic-model

Bases: BaseModel

An admin's decision to decline an access request.

reason is chosen from a fixed list and is what the applicant is told. note is the reviewer's own words: it is recorded with the decision and is never sent, because an explanation written for a colleague should not become an external statement about a named person.

Fields:

note = None pydantic-field

The reviewer's note, for the audit record. Never sent to the applicant.

notify = True pydantic-field

Whether to email the applicant. Leave true unless there is a reason not to reach this address at all.

reason pydantic-field

Why the request was declined. The applicant is told this, in the platform's own wording, unless the reason carries no detail.

AdminUserUpdate pydantic-model

Bases: BaseModel

Admin user update request; an omitted field is left unchanged.

The account's own settings only: an organization's limits and credits are set on the organization (:class:AdminOrganizationUpdate, :class:CreditAdjustment). An unknown field is refused, not ignored, so a limit sent here fails instead of silently changing nothing.

Config:

  • extra: forbid

Fields:

Validators:

  • _switches_or_permissions

can_create_api_keys = None pydantic-field

Grant (true) or withdraw (false) the ability to create API keys. Same mechanism as can_upload, on the api-key-create permission. Withdrawing leaves existing keys working and revocable; it stops new ones. Cannot be combined with permissions in one request.

can_submit = None pydantic-field

Grant (true) or withdraw (false) the ability to submit analyses. Same mechanism as can_upload, on the analysis-create permission. Cannot be combined with permissions in one request.

can_upload = None pydantic-field

Grant (true) or withdraw (false) the ability to register recordings. The server edits the permission set accordingly — withdrawing expands a wildcard grant into its other members — so this is the same gate the recording routes check, not a second one. Cannot be combined with permissions in one request.

disabled = None pydantic-field

Whether to disable or enable the user.

email = None pydantic-field

New email address.

organization = None pydantic-field

New organization.

password = None pydantic-field

New password.

permissions = None pydantic-field

New permissions list.

position = None pydantic-field

New position.

role = None pydantic-field

New authorization role (user or admin).

usage_type = None pydantic-field

New usage type. Switching changes which licence the user must consent to (they are re-gated on the new licence) and which analysis configs they may run — but outputs keep the licence they were produced under.

CreditAdjustment pydantic-model

Bases: BaseModel

A signed change to an organization's purchased credits, with its reason.

Fields:

amount pydantic-field

Amount to adjust. Positive to add, negative to deduct.

reason pydantic-field

Reason for the adjustment (logged for audit trail).

PlatformStats pydantic-model

Bases: BaseModel

Platform-wide statistics.

Fields:

active_users pydantic-field

Users that are NOT DISABLED. This counts accounts in good standing, not accounts in use — an account that has never been signed into is counted here. For actual usage read recently_active_users, which is what 'active' normally means to a reader.

analyses_by_status pydantic-field

Live analyses that have not yet settled, by status — the queue as it stands at the time of the request. Statuses with no live analyses are absent rather than zero.

pending_approvals pydantic-field

Accounts that registered and await an administrator's approval before they can sign in.

recently_active_days pydantic-field

The window recently_active_users counts over, in days. Reported alongside the count so a reader never has to guess what 'recently' meant, and so the window can change without silently changing what the number means.

recently_active_users pydantic-field

Users who signed in within recently_active_days. The honest activity figure: derived from each account's last sign-in, so it falls when people stop using the platform, which active_users does not.

registrations_24h pydantic-field

Accounts created in the last 24 hours, whatever their approval state. A burst here is what the registration control answers.

storage_bytes_stored pydantic-field

Bytes actually held across the platform, regardless of whether they count toward an allowance — the 'how much data do we hold' figure, which answers capacity and cost rather than billing. The gap against storage_bytes_total is the storage the platform pays for and does not charge for. Live resources only.

storage_bytes_total pydantic-field

Bytes counting toward storage ALLOWANCES across the platform — what the platform bills for. Excludes resource types configured not to count toward quota and anything external, so it is not the amount of data held; read storage_bytes_stored for that. Live resources only; soft-deleted ones are excluded, matching how per-org quota is measured.

StorageBucketReconciliation pydantic-model

Bases: BaseModel

One bucket's objects compared with the storage records that reference them.

Fields:

awaiting_reap pydantic-field

Objects referenced only by deleted records, still waiting to be removed.

missing pydantic-field

Live records whose object is gone. Anything above zero means stored data is lost and warrants immediate attention.

missing_sample pydantic-field

Some of the missing object keys, capped by the server.

objects pydantic-field

Objects in the bucket.

tracked_live pydantic-field

Live records that reference an object in the bucket. Records with a scheduled expiry are not counted.

untracked pydantic-field

Objects that no record references.

untracked_sample pydantic-field

Some of the untracked object keys, capped by the server.

StorageReconciliationNeverRun pydantic-model

Bases: BaseModel

The answer when no reconciliation report is stored.

Either none has run yet, or the last report has expired.

Fields:

  • status (Literal['never_run'])

StorageReconciliationReport pydantic-model

Bases: BaseModel

The last storage reconciliation.

Each data bucket's objects compared with the storage records, both ways. The report names drift and changes nothing; what to do about it is an operator's decision.

Fields:

buckets pydantic-field

The comparison for each bucket, by bucket name.

duration_seconds pydantic-field

How long the reconciliation took.

missing_total pydantic-field

Missing objects across all buckets.

timestamp pydantic-field

When the reconciliation ran.

untracked_total pydantic-field

Untracked objects across all buckets.