Skip to content
Authrim

Get data retention status.

GET
/api/admin/data-retention/status
Code sample: Shell / cURL 
curl --request GET \
  --url https://auth.example.com/api/admin/data-retention/status \
  --header 'Authorization: Bearer <token>'

Returns every retention category with record counts, the records past retention, and the categories whose data is not being removed as its retention says (a disabled or failed retention task, a failed or unsupported run for this tenant, logs kept only in an archive Authrim does not delete, or a lookup policy not yet projected).

Authorizations

Section titled “Authorizations ”

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Data retention status response.

Media type application/json
object
tenant_id
required
string
categories
required
Array<object>
object
id
required
string
Allowed values: audit_events audit_pii check_api_audit user_tombstones compliance_reports lookup_directory diagnostic_logs sessions refresh_tokens authorization_codes access_tokens
retention
required
object
value
required
number
> 0
unit
required
string
Allowed values: days seconds
key
additional properties
source
required

What decides the retention. setting (with category, key and level), session_settings (with keys), audit (with from: delivery_plan, audit_profile or pii_config), lookup_policy, or default (each record may have its own, set when it is made).

object
kind
required
string
Allowed values: setting session_settings audit lookup_policy default
category
string
key
string
level
string
Allowed values: tenant platform
keys
Array<string>
from
string
Allowed values: delivery_plan audit_profile pii_config
edit
required

Where an admin changes it: settings (Settings API category, key and level), session_settings, audit_pii_config, audit_profile, audit_routing_rules, lookup_directory (this API), or none.

object
kind
required
string
Allowed values: settings session_settings audit_pii_config audit_profile audit_routing_rules lookup_directory none
category
string
key
string
level
string
Allowed values: tenant platform
deletion
required

What removes the data: a scheduled_task (with its state and this tenant’s last run), expiry where it is kept, not_stored, or not_deleted (nothing removes it yet: the lookup directory, whose policy is projected to Control without a purge acting on it, and expired refresh token families, kept until rotated or revoked).

object
kind
required
string
Allowed values: scheduled_task expiry not_stored not_deleted
reason
string
Allowed values: lookup_purge_not_available expired_refresh_families_kept
task
string
enabled
boolean
disabled_reason
string | null
status
string
last_started_at
integer | null
last_completed_at
integer | null
last_error_code
string | null
next_run_at
integer | null
tenant_last_run

When the task last ran for this tenant. A run covers only some tenants (and, for diagnostic logs, one page of objects each; a tenant is recorded once all its objects were scanned), so the task’s own last run says nothing about this one.

object
at
required
integer
outcome
required
string
Allowed values: cleaned archive_only not_supported archive_copy_failed failed
projection
string
Allowed values: current pending
varies
required
string | null
Allowed values: by_route by_app by_sign_in_method by_request
cap

A limit below the setting that applies instead (the tenant profile’s token lifetime).

object
kind
required
string
Allowed values: tenant_profile
seconds
required
integer
counts
required
object
total
required
integer
expired
required
integer
extension

For sessions: an active session can be extended by per_refresh_seconds at a time; absolute_limit_seconds null means nothing bounds how long it may last in all.

object
per_refresh_seconds
required
integer
absolute_limit_seconds
required
integer | null
breakdown
Array<object>
object
key
required
string
seconds
required
integer
fixed

A lifetime fixed in code for this sign-in path (key names the path).

boolean
archive

Audit logs only: a copy also goes to an archive (R2). The deletion covers the primary store only; Authrim deletes nothing from the archive (an R2 lifecycle rule set outside Authrim may).

object
deletion
required
string
Allowed values: not_deleted
key
additional properties
summary
required
object
expired_records
required
integer
attention
required
Array<object>
object
category
required
string
Allowed values: audit_events audit_pii check_api_audit user_tombstones compliance_reports lookup_directory diagnostic_logs sessions refresh_tokens authorization_codes access_tokens
reason
required
string
Allowed values: task_disabled task_failed never_run tenant_run_failed deleted_outside_authrim not_deleted projection_pending no_absolute_limit archive_not_deleted
generated_at
required
string format: date-time
key
additional properties
Example 
{
  "categories": [
    {
      "id": "audit_events",
      "retention": {
        "unit": "days"
      },
      "source": {
        "kind": "setting",
        "level": "tenant",
        "from": "delivery_plan"
      },
      "edit": {
        "kind": "settings",
        "level": "tenant"
      },
      "deletion": {
        "kind": "scheduled_task",
        "reason": "lookup_purge_not_available",
        "tenant_last_run": {
          "outcome": "cleaned"
        },
        "projection": "current"
      },
      "varies": "by_route",
      "cap": {
        "kind": "tenant_profile"
      },
      "archive": {
        "deletion": "not_deleted"
      }
    }
  ],
  "summary": {
    "attention": [
      {
        "category": "audit_events",
        "reason": "task_disabled"
      }
    ]
  }
}

401

Section titled “401 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

403

Section titled “403 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

503

Section titled “503 ”

What decides a retention cannot be read, so the values in effect are unknown.