Reports: what can be queried, and the jobs that run a query.

The reports API. Every operation takes an access token for this realm’s /report-api carrying report:use or report:admin — the public client sts-report’s, DPoP-bound and sent as Authorization: DPoP, or an application’s own (client_credentials) where the application is a member of REPORT_USE or REPORT_ADMIN and declares the scope. The scopes are the permissions of those two roles; the access-control policy decides every definition and job: an owner their own, a report administrator every one, a shared group’s member reading and running one shared with them, an application only what it defined. A job id is not an authorization: retrieving a result takes the same token. Paths are after the realm prefix; the default realm has none. The catalog is the field reference. A query names one source. An offset, a second source and a SQL statement are invalid_query. Errors are English. The body never carries an STS-REPORT code.

Every answer is checked against the model shown here before it is sent, and no answer carries a member its model does not list. A member shown as any JSON is one whose shape belongs to somebody else, and says whose. .{key} is a key that is data, and [] an element of a list.

A refusal

Unless an operation below says otherwise, any status it does not list answers this:

Member Type Required What it is
error string    
error_description string    

GET /report-api

getIndex

The report API index

Names the catalog and realms addresses, and carries the service version the application draws in its footer.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The index.

Member Type Required What it is
catalog string    
realms string    
service string    
version object    
version.buildInfo string    
version.stamped boolean    
version.version string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

GET /report-api/announcements

getAnnouncements

Announcements for everybody signed in

What an administrator broadcast to this application (#1086) after since — the now this operation answered the tab’s first ask with — within ssf.announcementKeepS, oldest first. With no since it answers only now. everyMs is how often an open tab asks again.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
since query integer    
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: now, everyMs and announcements.

Member Type Required What it is
announcements list    
announcements[].at string    
announcements[].id string    
announcements[].message string    
everyMs number, or null    
now number   This service’s clock, in milliseconds: the since of the next ask.

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

GET /report-api/catalog

getCatalog

The report catalog

Every source. Each field has an id, a meaning, a type, whether it can be filtered, sorted or grouped, and its operators. paging is limit. relationships is empty. retention is the English sentence for how long the rows last.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The sources.

Member Type Required What it is
sources list    
sources[].anchored boolean   True for a source read from the directory (users, credentialHolders): a filter on it has to name a field whose indexed list holds the operator — a leaf of an and, or every arm of an or — or it is refused as invalid_query; the other fields narrow an indexed read.
sources[].bounded boolean    
sources[].fields list    
sources[].fields[].filter boolean    
sources[].fields[].group boolean    
sources[].fields[].id string    
sources[].fields[].indexed list   The operators the directory answers with an index, so a filter using one of them reads only the rows it names. A users query whose filter uses none, with an order or a count, or on a sealed field, reads every person: refused in sync mode (result_too_large), a job in auto mode.
sources[].fields[].indexed[] string    
sources[].fields[].indexedValues list   The values whose equality the index answers, when it answers only some: users status is indexed for locked, and active is everybody else. Absent when every value is answered.
sources[].fields[].indexedValues[] string    
sources[].fields[].meaning string    
sources[].fields[].operators list    
sources[].fields[].operators[] string    
sources[].fields[].sort boolean    
sources[].fields[].type one of string, number, boolean, timestamp    
sources[].fields[].values list   Every value the field can hold, when it is an enumeration; the page draws a dropdown of them for equals and not equals. Absent for an open field.
sources[].fields[].values[] string    
sources[].id one of users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions    
sources[].paging one of limit    
sources[].presets list   Predefined queries (#1110): a name and a whole query document the page offers as a starting point. Data, not a stored definition: nobody owns one and nothing runs it until somebody does.
sources[].presets[].document object    
sources[].presets[].document.aggregate one of count, null    
sources[].presets[].document.format one of json, csv, pdf    
sources[].presets[].document.groupBy list   The fields a count groups by, at most 8, each once.
sources[].presets[].document.groupBy[] string    
sources[].presets[].document.limit integer    
sources[].presets[].document.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
sources[].presets[].document.mode one of auto, sync, async    
sources[].presets[].document.orderBy list   At most 8 entries, each a field and a direction, and a field once.
sources[].presets[].document.orderBy[].dir one of asc, desc yes  
sources[].presets[].document.orderBy[].field string yes  
sources[].presets[].document.select list   The fields, at most 64, each once. A count may name none, as three presets do.
sources[].presets[].document.select[] string    
sources[].presets[].document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
sources[].presets[].document.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
sources[].presets[].document.where (shape 1) object   and or or over between 1 and 16 filters.
sources[].presets[].document.where (shape 1).args list yes  
sources[].presets[].document.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
sources[].presets[].document.where (shape 1).op one of and, or yes  
sources[].presets[].document.where (shape 2) object   not over one filter.
sources[].presets[].document.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
sources[].presets[].document.where (shape 2).op one of not yes  
sources[].presets[].document.where (shape 3) object   isNull names the field and nothing else.
sources[].presets[].document.where (shape 3).field string yes  
sources[].presets[].document.where (shape 3).op one of isNull yes  
sources[].presets[].document.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
sources[].presets[].document.where (shape 4).field string yes  
sources[].presets[].document.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
sources[].presets[].document.where (shape 4).value string, or null, or number, or boolean yes  
sources[].presets[].document.where (shape 5) object   in, with between 1 and 50 values.
sources[].presets[].document.where (shape 5).field string yes  
sources[].presets[].document.where (shape 5).op one of in yes  
sources[].presets[].document.where (shape 5).value list yes  
sources[].presets[].document.where (shape 5).value[] object   Nested deeper than this page draws.
sources[].presets[].document.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
sources[].presets[].document.where (shape 6).field string yes  
sources[].presets[].document.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
sources[].presets[].document.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
sources[].presets[].id string    
sources[].presets[].name string    
sources[].relationships list    
sources[].relationships[] string    
sources[].retention string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

GET /report-api/catalog/{id}

getCatalogSource

One report source

The same object the catalog lists for one id.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The source id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The source.

Member Type Required What it is
source object    
source.anchored boolean   True for a source read from the directory (users, credentialHolders): a filter on it has to name a field whose indexed list holds the operator — a leaf of an and, or every arm of an or — or it is refused as invalid_query; the other fields narrow an indexed read.
source.bounded boolean    
source.fields list    
source.fields[].filter boolean    
source.fields[].group boolean    
source.fields[].id string    
source.fields[].indexed list   The operators the directory answers with an index, so a filter using one of them reads only the rows it names. A users query whose filter uses none, with an order or a count, or on a sealed field, reads every person: refused in sync mode (result_too_large), a job in auto mode.
source.fields[].indexed[] string    
source.fields[].indexedValues list   The values whose equality the index answers, when it answers only some: users status is indexed for locked, and active is everybody else. Absent when every value is answered.
source.fields[].indexedValues[] string    
source.fields[].meaning string    
source.fields[].operators list    
source.fields[].operators[] string    
source.fields[].sort boolean    
source.fields[].type one of string, number, boolean, timestamp    
source.fields[].values list   Every value the field can hold, when it is an enumeration; the page draws a dropdown of them for equals and not equals. Absent for an open field.
source.fields[].values[] string    
source.id one of users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions    
source.paging one of limit    
source.presets list   Predefined queries (#1110): a name and a whole query document the page offers as a starting point. Data, not a stored definition: nobody owns one and nothing runs it until somebody does.
source.presets[].document object    
source.presets[].document.aggregate one of count, null    
source.presets[].document.format one of json, csv, pdf    
source.presets[].document.groupBy list   The fields a count groups by, at most 8, each once.
source.presets[].document.groupBy[] string    
source.presets[].document.limit integer    
source.presets[].document.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
source.presets[].document.mode one of auto, sync, async    
source.presets[].document.orderBy list   At most 8 entries, each a field and a direction, and a field once.
source.presets[].document.orderBy[].dir one of asc, desc yes  
source.presets[].document.orderBy[].field string yes  
source.presets[].document.select list   The fields, at most 64, each once. A count may name none, as three presets do.
source.presets[].document.select[] string    
source.presets[].document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
source.presets[].document.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
source.presets[].document.where (shape 1) object   and or or over between 1 and 16 filters.
source.presets[].document.where (shape 1).args list yes  
source.presets[].document.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
source.presets[].document.where (shape 1).op one of and, or yes  
source.presets[].document.where (shape 2) object   not over one filter.
source.presets[].document.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
source.presets[].document.where (shape 2).op one of not yes  
source.presets[].document.where (shape 3) object   isNull names the field and nothing else.
source.presets[].document.where (shape 3).field string yes  
source.presets[].document.where (shape 3).op one of isNull yes  
source.presets[].document.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
source.presets[].document.where (shape 4).field string yes  
source.presets[].document.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
source.presets[].document.where (shape 4).value string, or null, or number, or boolean yes  
source.presets[].document.where (shape 5) object   in, with between 1 and 50 values.
source.presets[].document.where (shape 5).field string yes  
source.presets[].document.where (shape 5).op one of in yes  
source.presets[].document.where (shape 5).value list yes  
source.presets[].document.where (shape 5).value[] string, or null, or number, or boolean    
source.presets[].document.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
source.presets[].document.where (shape 6).field string yes  
source.presets[].document.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
source.presets[].document.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
source.presets[].id string    
source.presets[].name string    
source.relationships list    
source.relationships[] string    
source.retention string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: unknown_source.

Member Type Required What it is
error string    
error_description string    

GET /report-api/definitions

getDefinitions

List definitions

The caller’s own definitions, those shared with a group the caller belongs to, and every definition when the token has report:admin. In name order, numbered pages: page and per (50 unless given, at most 200); the answer carries page, pages, per and total beside the rows. limit is the older spelling of per, read when per is absent.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
page query integer    
per query integer    
limit query integer   The older spelling of per.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The definitions.

Member Type Required What it is
definitions list    
definitions[].createdAt string, date-time, or null    
definitions[].document object    
definitions[].document.aggregate one of count, null    
definitions[].document.format one of json, csv, pdf    
definitions[].document.groupBy list   The fields a count groups by, at most 8, each once.
definitions[].document.groupBy[] string    
definitions[].document.limit integer    
definitions[].document.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
definitions[].document.mode one of auto, sync, async    
definitions[].document.orderBy list   At most 8 entries, each a field and a direction, and a field once.
definitions[].document.orderBy[].dir one of asc, desc yes  
definitions[].document.orderBy[].field string yes  
definitions[].document.select list   The fields, at most 64, each once. A count may name none, as three presets do.
definitions[].document.select[] string    
definitions[].document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
definitions[].document.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
definitions[].document.where (shape 1) object   and or or over between 1 and 16 filters.
definitions[].document.where (shape 1).args list yes  
definitions[].document.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definitions[].document.where (shape 1).op one of and, or yes  
definitions[].document.where (shape 2) object   not over one filter.
definitions[].document.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definitions[].document.where (shape 2).op one of not yes  
definitions[].document.where (shape 3) object   isNull names the field and nothing else.
definitions[].document.where (shape 3).field string yes  
definitions[].document.where (shape 3).op one of isNull yes  
definitions[].document.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
definitions[].document.where (shape 4).field string yes  
definitions[].document.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
definitions[].document.where (shape 4).value string, or null, or number, or boolean yes  
definitions[].document.where (shape 5) object   in, with between 1 and 50 values.
definitions[].document.where (shape 5).field string yes  
definitions[].document.where (shape 5).op one of in yes  
definitions[].document.where (shape 5).value list yes  
definitions[].document.where (shape 5).value[] string, or null, or number, or boolean    
definitions[].document.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
definitions[].document.where (shape 6).field string yes  
definitions[].document.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
definitions[].document.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
definitions[].editable boolean    
definitions[].failures list    
definitions[].failures[] object   A run a schedule skipped: reportNoteFailure().
definitions[].failures[].at number   When, in milliseconds.
definitions[].failures[].description string    
definitions[].groups list    
definitions[].groups[] string    
definitions[].id string    
definitions[].lastSlotAt string, or null   The most recent occurrence the schedule has taken (queued, or skipped with a note), or null.
definitions[].modifiedAt string, date-time, or null    
definitions[].name string    
definitions[].nextRunAt string, or null   When the enabled schedule next occurs, ISO-8601 UTC; null when it is off or has no occurrence.
definitions[].notify boolean    
definitions[].owner string   The owner’s subject (urn:uuid:…).
definitions[].ownerName string   The owner’s display name, or username; empty for a subject this realm cannot name.
definitions[].parameters map   Parameter name to the value the filter uses: at most 32 names of 1 to 64 characters. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none, or a run gives none.
definitions[].parameters.{key} list, or string, or null, or number, or boolean    
definitions[].parameters.{key}[] string, or null, or number, or boolean    
definitions[].schedule string   A five-field cron expression in UTC, or empty. The application composes it from a date-time and weekday boxes.
definitions[].scheduleEnabled boolean    
page integer    
pages integer    
per integer    
total integer    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

POST /report-api/definitions

createDefinition

Create a definition

Stores the document. parameters is the bag a schedule runs with. A missing value can still be type-checked; it is not stored as a dummy, and the schedule will not run until the value is saved.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

Request body (optional)

Member Type Required What it is
document object yes  
document.aggregate one of count, null    
document.format one of json, csv, pdf    
document.groupBy list   The fields a count groups by, at most 8, each once.
document.groupBy[] string    
document.limit integer    
document.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
document.mode one of auto, sync, async    
document.orderBy list   At most 8 entries, each a field and a direction, and a field once.
document.orderBy[].dir one of asc, desc yes  
document.orderBy[].field string yes  
document.select list   The fields, at most 64, each once. A count may name none, as three presets do.
document.select[] string    
document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
document.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
document.where (shape 1) object   and or or over between 1 and 16 filters.
document.where (shape 1).args list yes  
document.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
document.where (shape 1).op one of and, or yes  
document.where (shape 2) object   not over one filter.
document.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
document.where (shape 2).op one of not yes  
document.where (shape 3) object   isNull names the field and nothing else.
document.where (shape 3).field string yes  
document.where (shape 3).op one of isNull yes  
document.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
document.where (shape 4).field string yes  
document.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
document.where (shape 4).value string, or null, or number, or boolean yes  
document.where (shape 5) object   in, with between 1 and 50 values.
document.where (shape 5).field string yes  
document.where (shape 5).op one of in yes  
document.where (shape 5).value list yes  
document.where (shape 5).value[] string, or null, or number, or boolean    
document.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
document.where (shape 6).field string yes  
document.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
document.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
name string yes What the definition is called: at most 120 characters, not only spaces.
notify boolean   Mail the owner when a scheduled run finishes. The message links to the job. It does not contain rows.
parameters map   Parameter name to the value the filter uses: at most 32 names of 1 to 64 characters. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none, or a run gives none.
parameters.{key} list, or string, or null, or number, or boolean    
parameters.{key}[] string, or null, or number, or boolean    
schedule string   A UTC cron expression, or empty.
scheduleEnabled boolean    

200: The stored definition.

Member Type Required What it is
definition object    
definition.createdAt string, date-time, or null    
definition.document object    
definition.document.aggregate one of count, null    
definition.document.format one of json, csv, pdf    
definition.document.groupBy list   The fields a count groups by, at most 8, each once.
definition.document.groupBy[] string    
definition.document.limit integer    
definition.document.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
definition.document.mode one of auto, sync, async    
definition.document.orderBy list   At most 8 entries, each a field and a direction, and a field once.
definition.document.orderBy[].dir one of asc, desc yes  
definition.document.orderBy[].field string yes  
definition.document.select list   The fields, at most 64, each once. A count may name none, as three presets do.
definition.document.select[] string    
definition.document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
definition.document.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
definition.document.where (shape 1) object   and or or over between 1 and 16 filters.
definition.document.where (shape 1).args list yes  
definition.document.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where (shape 1).op one of and, or yes  
definition.document.where (shape 2) object   not over one filter.
definition.document.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where (shape 2).op one of not yes  
definition.document.where (shape 3) object   isNull names the field and nothing else.
definition.document.where (shape 3).field string yes  
definition.document.where (shape 3).op one of isNull yes  
definition.document.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
definition.document.where (shape 4).field string yes  
definition.document.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
definition.document.where (shape 4).value string, or null, or number, or boolean yes  
definition.document.where (shape 5) object   in, with between 1 and 50 values.
definition.document.where (shape 5).field string yes  
definition.document.where (shape 5).op one of in yes  
definition.document.where (shape 5).value list yes  
definition.document.where (shape 5).value[] string, or null, or number, or boolean    
definition.document.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
definition.document.where (shape 6).field string yes  
definition.document.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
definition.document.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
definition.editable boolean    
definition.failures list    
definition.failures[] object   A run a schedule skipped: reportNoteFailure().
definition.failures[].at number   When, in milliseconds.
definition.failures[].description string    
definition.groups list    
definition.groups[] string    
definition.id string    
definition.lastSlotAt string, or null   The most recent occurrence the schedule has taken (queued, or skipped with a note), or null.
definition.modifiedAt string, date-time, or null    
definition.name string    
definition.nextRunAt string, or null   When the enabled schedule next occurs, ISO-8601 UTC; null when it is off or has no occurrence.
definition.notify boolean    
definition.owner string   The owner’s subject (urn:uuid:…).
definition.ownerName string   The owner’s display name, or username; empty for a subject this realm cannot name.
definition.parameters map   Parameter name to the value the filter uses: at most 32 names of 1 to 64 characters. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none, or a run gives none.
definition.parameters.{key} list, or string, or null, or number, or boolean    
definition.parameters.{key}[] string, or null, or number, or boolean    
definition.schedule string   A five-field cron expression in UTC, or empty. The application composes it from a date-time and weekday boxes.
definition.scheduleEnabled boolean    

400: invalid_query.

Member Type Required What it is
error string    
error_description string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

GET /report-api/definitions/{id}

getDefinition

Read a definition

An id the caller may not see is not_found, the same answer as an id that does not exist.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The definition id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The definition.

Member Type Required What it is
definition object    
definition.createdAt string, date-time, or null    
definition.document object    
definition.document.aggregate one of count, null    
definition.document.format one of json, csv, pdf    
definition.document.groupBy list   The fields a count groups by, at most 8, each once.
definition.document.groupBy[] string    
definition.document.limit integer    
definition.document.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
definition.document.mode one of auto, sync, async    
definition.document.orderBy list   At most 8 entries, each a field and a direction, and a field once.
definition.document.orderBy[].dir one of asc, desc yes  
definition.document.orderBy[].field string yes  
definition.document.select list   The fields, at most 64, each once. A count may name none, as three presets do.
definition.document.select[] string    
definition.document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
definition.document.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
definition.document.where (shape 1) object   and or or over between 1 and 16 filters.
definition.document.where (shape 1).args list yes  
definition.document.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where (shape 1).op one of and, or yes  
definition.document.where (shape 2) object   not over one filter.
definition.document.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where (shape 2).op one of not yes  
definition.document.where (shape 3) object   isNull names the field and nothing else.
definition.document.where (shape 3).field string yes  
definition.document.where (shape 3).op one of isNull yes  
definition.document.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
definition.document.where (shape 4).field string yes  
definition.document.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
definition.document.where (shape 4).value string, or null, or number, or boolean yes  
definition.document.where (shape 5) object   in, with between 1 and 50 values.
definition.document.where (shape 5).field string yes  
definition.document.where (shape 5).op one of in yes  
definition.document.where (shape 5).value list yes  
definition.document.where (shape 5).value[] string, or null, or number, or boolean    
definition.document.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
definition.document.where (shape 6).field string yes  
definition.document.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
definition.document.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
definition.editable boolean    
definition.failures list    
definition.failures[] object   A run a schedule skipped: reportNoteFailure().
definition.failures[].at number   When, in milliseconds.
definition.failures[].description string    
definition.groups list    
definition.groups[] string    
definition.id string    
definition.lastSlotAt string, or null   The most recent occurrence the schedule has taken (queued, or skipped with a note), or null.
definition.modifiedAt string, date-time, or null    
definition.name string    
definition.nextRunAt string, or null   When the enabled schedule next occurs, ISO-8601 UTC; null when it is off or has no occurrence.
definition.notify boolean    
definition.owner string   The owner’s subject (urn:uuid:…).
definition.ownerName string   The owner’s display name, or username; empty for a subject this realm cannot name.
definition.parameters map   Parameter name to the value the filter uses: at most 32 names of 1 to 64 characters. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none, or a run gives none.
definition.parameters.{key} list, or string, or null, or number, or boolean    
definition.parameters.{key}[] string, or null, or number, or boolean    
definition.schedule string   A five-field cron expression in UTC, or empty. The application composes it from a date-time and weekday boxes.
definition.scheduleEnabled boolean    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: not_found.

Member Type Required What it is
error string    
error_description string    

POST /report-api/definitions/{id}

replaceDefinition

Replace a definition

The owner, or report:admin. parameters omitted keeps the stored bag. parameters null clears it.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The definition id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

Request body (optional)

Member Type Required What it is
document object yes  
document.aggregate one of count, null    
document.format one of json, csv, pdf    
document.groupBy list   The fields a count groups by, at most 8, each once.
document.groupBy[] string    
document.limit integer    
document.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
document.mode one of auto, sync, async    
document.orderBy list   At most 8 entries, each a field and a direction, and a field once.
document.orderBy[].dir one of asc, desc yes  
document.orderBy[].field string yes  
document.select list   The fields, at most 64, each once. A count may name none, as three presets do.
document.select[] string    
document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
document.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
document.where (shape 1) object   and or or over between 1 and 16 filters.
document.where (shape 1).args list yes  
document.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
document.where (shape 1).op one of and, or yes  
document.where (shape 2) object   not over one filter.
document.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
document.where (shape 2).op one of not yes  
document.where (shape 3) object   isNull names the field and nothing else.
document.where (shape 3).field string yes  
document.where (shape 3).op one of isNull yes  
document.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
document.where (shape 4).field string yes  
document.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
document.where (shape 4).value string, or null, or number, or boolean yes  
document.where (shape 5) object   in, with between 1 and 50 values.
document.where (shape 5).field string yes  
document.where (shape 5).op one of in yes  
document.where (shape 5).value list yes  
document.where (shape 5).value[] string, or null, or number, or boolean    
document.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
document.where (shape 6).field string yes  
document.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
document.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
name string yes What the definition is called: at most 120 characters, not only spaces.
notify boolean   Mail the owner when a scheduled run finishes. The message links to the job. It does not contain rows.
parameters map   Parameter name to the value the filter uses: at most 32 names of 1 to 64 characters. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none, or a run gives none.
parameters.{key} list, or string, or null, or number, or boolean    
parameters.{key}[] string, or null, or number, or boolean    
schedule string   A UTC cron expression, or empty.
scheduleEnabled boolean    

200: The stored definition.

Member Type Required What it is
definition object    
definition.createdAt string, date-time, or null    
definition.document object    
definition.document.aggregate one of count, null    
definition.document.format one of json, csv, pdf    
definition.document.groupBy list   The fields a count groups by, at most 8, each once.
definition.document.groupBy[] string    
definition.document.limit integer    
definition.document.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
definition.document.mode one of auto, sync, async    
definition.document.orderBy list   At most 8 entries, each a field and a direction, and a field once.
definition.document.orderBy[].dir one of asc, desc yes  
definition.document.orderBy[].field string yes  
definition.document.select list   The fields, at most 64, each once. A count may name none, as three presets do.
definition.document.select[] string    
definition.document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
definition.document.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
definition.document.where (shape 1) object   and or or over between 1 and 16 filters.
definition.document.where (shape 1).args list yes  
definition.document.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where (shape 1).op one of and, or yes  
definition.document.where (shape 2) object   not over one filter.
definition.document.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where (shape 2).op one of not yes  
definition.document.where (shape 3) object   isNull names the field and nothing else.
definition.document.where (shape 3).field string yes  
definition.document.where (shape 3).op one of isNull yes  
definition.document.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
definition.document.where (shape 4).field string yes  
definition.document.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
definition.document.where (shape 4).value string, or null, or number, or boolean yes  
definition.document.where (shape 5) object   in, with between 1 and 50 values.
definition.document.where (shape 5).field string yes  
definition.document.where (shape 5).op one of in yes  
definition.document.where (shape 5).value list yes  
definition.document.where (shape 5).value[] string, or null, or number, or boolean    
definition.document.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
definition.document.where (shape 6).field string yes  
definition.document.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
definition.document.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
definition.editable boolean    
definition.failures list    
definition.failures[] object   A run a schedule skipped: reportNoteFailure().
definition.failures[].at number   When, in milliseconds.
definition.failures[].description string    
definition.groups list    
definition.groups[] string    
definition.id string    
definition.lastSlotAt string, or null   The most recent occurrence the schedule has taken (queued, or skipped with a note), or null.
definition.modifiedAt string, date-time, or null    
definition.name string    
definition.nextRunAt string, or null   When the enabled schedule next occurs, ISO-8601 UTC; null when it is off or has no occurrence.
definition.notify boolean    
definition.owner string   The owner’s subject (urn:uuid:…).
definition.ownerName string   The owner’s display name, or username; empty for a subject this realm cannot name.
definition.parameters map   Parameter name to the value the filter uses: at most 32 names of 1 to 64 characters. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none, or a run gives none.
definition.parameters.{key} list, or string, or null, or number, or boolean    
definition.parameters.{key}[] string, or null, or number, or boolean    
definition.schedule string   A five-field cron expression in UTC, or empty. The application composes it from a date-time and weekday boxes.
definition.scheduleEnabled boolean    

400: invalid_query.

Member Type Required What it is
error string    
error_description string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: not_found.

Member Type Required What it is
error string    
error_description string    

DELETE /report-api/definitions/{id}

deleteDefinition

Delete a definition

The owner, or report:admin. A share cannot delete.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The definition id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: Deleted.

Member Type Required What it is
deleted string   The definition’s id.

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: not_found.

Member Type Required What it is
error string    
error_description string    

POST /report-api/definitions/{id}/run

runDefinition

Run a saved definition

Always a job. The body is a parameter object, not a query document. A key in the body overrides the stored default, and one the filter does not name is ignored. The body is held to a saved parameter bag’s bounds, names of 1 to 64 characters among them, and is not stored. An empty body uses the stored defaults. The stored document already carries locale.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The definition id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

Request body (optional)

Member Type Required What it is
(the answer) map   Parameter name to the value the filter uses: at most 32 names of 1 to 64 characters. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none, or a run gives none.
.{key} list, or string, or null, or number, or boolean    
.{key}[] string, or null, or number, or boolean    

202: The job.

Member Type Required What it is
job object    
job.byteSize integer, or null    
job.completedAt string, or null    
job.definitionId string, or null    
job.definitionName string, or null    
job.error string, or null   The public error token. A job that exceeded report.asyncMaxMs carries result_too_large. The body of a failed job is not partial.
job.fields list    
job.fields[] string    
job.format string    
job.id string    
job.query object    
job.query.aggregate one of count, null    
job.query.format one of json, csv, pdf    
job.query.groupBy list   The fields a count groups by, at most 8, each once.
job.query.groupBy[] string    
job.query.limit integer    
job.query.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
job.query.mode one of auto, sync, async    
job.query.orderBy list   At most 8 entries, each a field and a direction, and a field once.
job.query.orderBy[].dir one of asc, desc yes  
job.query.orderBy[].field string yes  
job.query.select list   The fields, at most 64, each once. A count may name none, as three presets do.
job.query.select[] string    
job.query.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
job.query.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
job.query.where (shape 1) object   and or or over between 1 and 16 filters.
job.query.where (shape 1).args list yes  
job.query.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where (shape 1).op one of and, or yes  
job.query.where (shape 2) object   not over one filter.
job.query.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where (shape 2).op one of not yes  
job.query.where (shape 3) object   isNull names the field and nothing else.
job.query.where (shape 3).field string yes  
job.query.where (shape 3).op one of isNull yes  
job.query.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
job.query.where (shape 4).field string yes  
job.query.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
job.query.where (shape 4).value string, or null, or number, or boolean yes  
job.query.where (shape 5) object   in, with between 1 and 50 values.
job.query.where (shape 5).field string yes  
job.query.where (shape 5).op one of in yes  
job.query.where (shape 5).value list yes  
job.query.where (shape 5).value[] string, or null, or number, or boolean    
job.query.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
job.query.where (shape 6).field string yes  
job.query.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
job.query.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
job.queuedBecause one of every-person, asked, limit, source, run, schedule, null   Why this query is a job: every-person (an auto-mode query whose filter the directory cannot answer from an index, so it has to read every person), asked (mode async, or POST /jobs), limit (auto over report.syncMaxRows), source (a source that cannot be read synchronously), run (a saved definition run by hand) or schedule.
job.source string    
job.status one of queued, running, completed, failed, cancelled, expired    
job.submittedAt string, or null    

400: invalid_query or result_too_large.

Member Type Required What it is
error string    
error_description string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: not_found.

Member Type Required What it is
error string    
error_description string    

429: too_many_jobs.

Member Type Required What it is
error string    
error_description string    

POST /report-api/definitions/{id}/share

shareDefinition

Share a definition

Replaces the group list. A share can run and retrieve. It cannot edit or delete. Each value is a group DN in this realm.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The definition id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

Request body (optional)

Member Type Required What it is
groups list yes  
groups[] string   A group’s DN in this realm.

200: The definition.

Member Type Required What it is
definition object    
definition.createdAt string, date-time, or null    
definition.document object    
definition.document.aggregate one of count, null    
definition.document.format one of json, csv, pdf    
definition.document.groupBy list   The fields a count groups by, at most 8, each once.
definition.document.groupBy[] string    
definition.document.limit integer    
definition.document.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
definition.document.mode one of auto, sync, async    
definition.document.orderBy list   At most 8 entries, each a field and a direction, and a field once.
definition.document.orderBy[].dir one of asc, desc yes  
definition.document.orderBy[].field string yes  
definition.document.select list   The fields, at most 64, each once. A count may name none, as three presets do.
definition.document.select[] string    
definition.document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
definition.document.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
definition.document.where (shape 1) object   and or or over between 1 and 16 filters.
definition.document.where (shape 1).args list yes  
definition.document.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where (shape 1).op one of and, or yes  
definition.document.where (shape 2) object   not over one filter.
definition.document.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where (shape 2).op one of not yes  
definition.document.where (shape 3) object   isNull names the field and nothing else.
definition.document.where (shape 3).field string yes  
definition.document.where (shape 3).op one of isNull yes  
definition.document.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
definition.document.where (shape 4).field string yes  
definition.document.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
definition.document.where (shape 4).value string, or null, or number, or boolean yes  
definition.document.where (shape 5) object   in, with between 1 and 50 values.
definition.document.where (shape 5).field string yes  
definition.document.where (shape 5).op one of in yes  
definition.document.where (shape 5).value list yes  
definition.document.where (shape 5).value[] string, or null, or number, or boolean    
definition.document.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
definition.document.where (shape 6).field string yes  
definition.document.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
definition.document.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
definition.editable boolean    
definition.failures list    
definition.failures[] object   A run a schedule skipped: reportNoteFailure().
definition.failures[].at number   When, in milliseconds.
definition.failures[].description string    
definition.groups list    
definition.groups[] string    
definition.id string    
definition.lastSlotAt string, or null   The most recent occurrence the schedule has taken (queued, or skipped with a note), or null.
definition.modifiedAt string, date-time, or null    
definition.name string    
definition.nextRunAt string, or null   When the enabled schedule next occurs, ISO-8601 UTC; null when it is off or has no occurrence.
definition.notify boolean    
definition.owner string   The owner’s subject (urn:uuid:…).
definition.ownerName string   The owner’s display name, or username; empty for a subject this realm cannot name.
definition.parameters map   Parameter name to the value the filter uses: at most 32 names of 1 to 64 characters. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none, or a run gives none.
definition.parameters.{key} list, or string, or null, or number, or boolean    
definition.parameters.{key}[] string, or null, or number, or boolean    
definition.schedule string   A five-field cron expression in UTC, or empty. The application composes it from a date-time and weekday boxes.
definition.scheduleEnabled boolean    

400: invalid_query.

Member Type Required What it is
error string    
error_description string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: not_found.

Member Type Required What it is
error string    
error_description string    

GET /report-api/groups

getGroups

Search the realm’s groups

The groups of this realm whose name or DN contains q (case-insensitive; empty matches every group), five a page in name order, each with its own mail attribute or an empty string. The definition page builds its share list from it; a definition’s groups are who is emailed its result, at that address (#989).

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
q query string    
page query integer    
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: One page of groups.

Member Type Required What it is
groups list    
groups[].dn string    
groups[].mail string   The group’s own address, or empty.
groups[].name string   The cn.
page integer    
pages integer    
per integer    
q string    
total integer    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

GET /report-api/jobs

getJobs

List jobs

Newest first, in numbered pages: page and per (50 unless given, at most 200), with page, pages, per and total beside the rows. A caller may page by cursor instead: after is the previous page’s next id and limit its size. A job id in the list is not permission to read a job the token cannot see.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
page query integer    
per query integer    
after query string   The last id of the previous page, for a cursor walk; page and per are then ignored.
limit query integer   How many jobs a cursor page returns.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The page. next is null on the last page.

Member Type Required What it is
jobs list    
jobs[].byteSize integer, or null    
jobs[].completedAt string, or null    
jobs[].definitionId string, or null    
jobs[].definitionName string, or null    
jobs[].error string, or null   The public error token. A job that exceeded report.asyncMaxMs carries result_too_large. The body of a failed job is not partial.
jobs[].fields list    
jobs[].fields[] string    
jobs[].format string    
jobs[].id string    
jobs[].query object    
jobs[].query.aggregate one of count, null    
jobs[].query.format one of json, csv, pdf    
jobs[].query.groupBy list   The fields a count groups by, at most 8, each once.
jobs[].query.groupBy[] string    
jobs[].query.limit integer    
jobs[].query.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
jobs[].query.mode one of auto, sync, async    
jobs[].query.orderBy list   At most 8 entries, each a field and a direction, and a field once.
jobs[].query.orderBy[].dir one of asc, desc yes  
jobs[].query.orderBy[].field string yes  
jobs[].query.select list   The fields, at most 64, each once. A count may name none, as three presets do.
jobs[].query.select[] string    
jobs[].query.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
jobs[].query.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
jobs[].query.where (shape 1) object   and or or over between 1 and 16 filters.
jobs[].query.where (shape 1).args list yes  
jobs[].query.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
jobs[].query.where (shape 1).op one of and, or yes  
jobs[].query.where (shape 2) object   not over one filter.
jobs[].query.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
jobs[].query.where (shape 2).op one of not yes  
jobs[].query.where (shape 3) object   isNull names the field and nothing else.
jobs[].query.where (shape 3).field string yes  
jobs[].query.where (shape 3).op one of isNull yes  
jobs[].query.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
jobs[].query.where (shape 4).field string yes  
jobs[].query.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
jobs[].query.where (shape 4).value string, or null, or number, or boolean yes  
jobs[].query.where (shape 5) object   in, with between 1 and 50 values.
jobs[].query.where (shape 5).field string yes  
jobs[].query.where (shape 5).op one of in yes  
jobs[].query.where (shape 5).value list yes  
jobs[].query.where (shape 5).value[] string, or null, or number, or boolean    
jobs[].query.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
jobs[].query.where (shape 6).field string yes  
jobs[].query.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
jobs[].query.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
jobs[].queuedBecause one of every-person, asked, limit, source, run, schedule, null   Why this query is a job: every-person (an auto-mode query whose filter the directory cannot answer from an index, so it has to read every person), asked (mode async, or POST /jobs), limit (auto over report.syncMaxRows), source (a source that cannot be read synchronously), run (a saved definition run by hand) or schedule.
jobs[].source string    
jobs[].status one of queued, running, completed, failed, cancelled, expired    
jobs[].submittedAt string, or null    
next string, or null    
page integer   Absent on a cursor page.
pages integer    
per integer    
total integer    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

POST /report-api/jobs

queueJob

Queue a job

The same document as a query, forced to a job even when it would have fit in one synchronous call.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

Request body (optional)

Member Type Required What it is
aggregate one of count, null    
format one of json, csv, pdf    
groupBy list   The fields a count groups by, at most 8, each once.
groupBy[] string    
limit integer    
locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
mode one of auto, sync, async    
orderBy list   At most 8 entries, each a field and a direction, and a field once.
orderBy[].dir one of asc, desc yes  
orderBy[].field string yes  
select list   The fields, at most 64, each once. A count may name none, as three presets do.
select[] string    
source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
where (shape 1) object   and or or over between 1 and 16 filters.
where (shape 1).args list yes  
where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
where (shape 1).op one of and, or yes  
where (shape 2) object   not over one filter.
where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
where (shape 2).op one of not yes  
where (shape 3) object   isNull names the field and nothing else.
where (shape 3).field string yes  
where (shape 3).op one of isNull yes  
where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
where (shape 4).field string yes  
where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
where (shape 4).value string, or null, or number, or boolean yes  
where (shape 5) object   in, with between 1 and 50 values.
where (shape 5).field string yes  
where (shape 5).op one of in yes  
where (shape 5).value list yes  
where (shape 5).value[] string, or null, or number, or boolean    
where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
where (shape 6).field string yes  
where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.

202: The job.

Member Type Required What it is
job object    
job.byteSize integer, or null    
job.completedAt string, or null    
job.definitionId string, or null    
job.definitionName string, or null    
job.error string, or null   The public error token. A job that exceeded report.asyncMaxMs carries result_too_large. The body of a failed job is not partial.
job.fields list    
job.fields[] string    
job.format string    
job.id string    
job.query object    
job.query.aggregate one of count, null    
job.query.format one of json, csv, pdf    
job.query.groupBy list   The fields a count groups by, at most 8, each once.
job.query.groupBy[] string    
job.query.limit integer    
job.query.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
job.query.mode one of auto, sync, async    
job.query.orderBy list   At most 8 entries, each a field and a direction, and a field once.
job.query.orderBy[].dir one of asc, desc yes  
job.query.orderBy[].field string yes  
job.query.select list   The fields, at most 64, each once. A count may name none, as three presets do.
job.query.select[] string    
job.query.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
job.query.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
job.query.where (shape 1) object   and or or over between 1 and 16 filters.
job.query.where (shape 1).args list yes  
job.query.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where (shape 1).op one of and, or yes  
job.query.where (shape 2) object   not over one filter.
job.query.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where (shape 2).op one of not yes  
job.query.where (shape 3) object   isNull names the field and nothing else.
job.query.where (shape 3).field string yes  
job.query.where (shape 3).op one of isNull yes  
job.query.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
job.query.where (shape 4).field string yes  
job.query.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
job.query.where (shape 4).value string, or null, or number, or boolean yes  
job.query.where (shape 5) object   in, with between 1 and 50 values.
job.query.where (shape 5).field string yes  
job.query.where (shape 5).op one of in yes  
job.query.where (shape 5).value list yes  
job.query.where (shape 5).value[] string, or null, or number, or boolean    
job.query.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
job.query.where (shape 6).field string yes  
job.query.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
job.query.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
job.queuedBecause one of every-person, asked, limit, source, run, schedule, null   Why this query is a job: every-person (an auto-mode query whose filter the directory cannot answer from an index, so it has to read every person), asked (mode async, or POST /jobs), limit (auto over report.syncMaxRows), source (a source that cannot be read synchronously), run (a saved definition run by hand) or schedule.
job.source string    
job.status one of queued, running, completed, failed, cancelled, expired    
job.submittedAt string, or null    

400: invalid_query, unknown_field, unsupported_operation or result_too_large.

Member Type Required What it is
error string    
error_description string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

429: too_many_jobs.

Member Type Required What it is
error string    
error_description string    

GET /report-api/jobs/{id}

getJob

Read a job

The owner and report:admin also receive the query document. A hidden id is job_not_found.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The job id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The job.

Member Type Required What it is
job object    
job.byteSize integer, or null    
job.completedAt string, or null    
job.definitionId string, or null    
job.definitionName string, or null    
job.error string, or null   The public error token. A job that exceeded report.asyncMaxMs carries result_too_large. The body of a failed job is not partial.
job.fields list    
job.fields[] string    
job.format string    
job.id string    
job.query object    
job.query.aggregate one of count, null    
job.query.format one of json, csv, pdf    
job.query.groupBy list   The fields a count groups by, at most 8, each once.
job.query.groupBy[] string    
job.query.limit integer    
job.query.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
job.query.mode one of auto, sync, async    
job.query.orderBy list   At most 8 entries, each a field and a direction, and a field once.
job.query.orderBy[].dir one of asc, desc yes  
job.query.orderBy[].field string yes  
job.query.select list   The fields, at most 64, each once. A count may name none, as three presets do.
job.query.select[] string    
job.query.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
job.query.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
job.query.where (shape 1) object   and or or over between 1 and 16 filters.
job.query.where (shape 1).args list yes  
job.query.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where (shape 1).op one of and, or yes  
job.query.where (shape 2) object   not over one filter.
job.query.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where (shape 2).op one of not yes  
job.query.where (shape 3) object   isNull names the field and nothing else.
job.query.where (shape 3).field string yes  
job.query.where (shape 3).op one of isNull yes  
job.query.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
job.query.where (shape 4).field string yes  
job.query.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
job.query.where (shape 4).value string, or null, or number, or boolean yes  
job.query.where (shape 5) object   in, with between 1 and 50 values.
job.query.where (shape 5).field string yes  
job.query.where (shape 5).op one of in yes  
job.query.where (shape 5).value list yes  
job.query.where (shape 5).value[] string, or null, or number, or boolean    
job.query.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
job.query.where (shape 6).field string yes  
job.query.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
job.query.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
job.queuedBecause one of every-person, asked, limit, source, run, schedule, null   Why this query is a job: every-person (an auto-mode query whose filter the directory cannot answer from an index, so it has to read every person), asked (mode async, or POST /jobs), limit (auto over report.syncMaxRows), source (a source that cannot be read synchronously), run (a saved definition run by hand) or schedule.
job.source string    
job.status one of queued, running, completed, failed, cancelled, expired    
job.submittedAt string, or null    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: job_not_found.

Member Type Required What it is
error string    
error_description string    

POST /report-api/jobs/{id}/cancel

cancelJob

Cancel a job

A queued job becomes cancelled. A running job is asked to stop and is not returned in part.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The job id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The job.

Member Type Required What it is
job object    
job.byteSize integer, or null    
job.completedAt string, or null    
job.definitionId string, or null    
job.definitionName string, or null    
job.error string, or null   The public error token. A job that exceeded report.asyncMaxMs carries result_too_large. The body of a failed job is not partial.
job.fields list    
job.fields[] string    
job.format string    
job.id string    
job.query object    
job.query.aggregate one of count, null    
job.query.format one of json, csv, pdf    
job.query.groupBy list   The fields a count groups by, at most 8, each once.
job.query.groupBy[] string    
job.query.limit integer    
job.query.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
job.query.mode one of auto, sync, async    
job.query.orderBy list   At most 8 entries, each a field and a direction, and a field once.
job.query.orderBy[].dir one of asc, desc yes  
job.query.orderBy[].field string yes  
job.query.select list   The fields, at most 64, each once. A count may name none, as three presets do.
job.query.select[] string    
job.query.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
job.query.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
job.query.where (shape 1) object   and or or over between 1 and 16 filters.
job.query.where (shape 1).args list yes  
job.query.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where (shape 1).op one of and, or yes  
job.query.where (shape 2) object   not over one filter.
job.query.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where (shape 2).op one of not yes  
job.query.where (shape 3) object   isNull names the field and nothing else.
job.query.where (shape 3).field string yes  
job.query.where (shape 3).op one of isNull yes  
job.query.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
job.query.where (shape 4).field string yes  
job.query.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
job.query.where (shape 4).value string, or null, or number, or boolean yes  
job.query.where (shape 5) object   in, with between 1 and 50 values.
job.query.where (shape 5).field string yes  
job.query.where (shape 5).op one of in yes  
job.query.where (shape 5).value list yes  
job.query.where (shape 5).value[] string, or null, or number, or boolean    
job.query.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
job.query.where (shape 6).field string yes  
job.query.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
job.query.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
job.queuedBecause one of every-person, asked, limit, source, run, schedule, null   Why this query is a job: every-person (an auto-mode query whose filter the directory cannot answer from an index, so it has to read every person), asked (mode async, or POST /jobs), limit (auto over report.syncMaxRows), source (a source that cannot be read synchronously), run (a saved definition run by hand) or schedule.
job.source string    
job.status one of queued, running, completed, failed, cancelled, expired    
job.submittedAt string, or null    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: job_not_found.

Member Type Required What it is
error string    
error_description string    

GET /report-api/jobs/{id}/result

getJobResult

Download a result

The artifact bytes. The media type is the format. A job id is not enough: the token must be allowed to see the job. Past artifact retention the result is gone.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The job id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The artifact. JSON, CSV or PDF.

As application/json:

Member Type Required What it is
fields list    
fields[] string    
rows list    
rows[] map   One row: a field’s id to what it holds. The keys are the fields the query selected, and count where it counted.
rows[].{key} list, or string, or null, or number, or boolean    
rows[].{key}[] string, or null, or number, or boolean    
source string    
truncated boolean    

As application/pdf.

As text/csv.

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: job_not_found.

Member Type Required What it is
error string    
error_description string    

409: job_not_ready.

Member Type Required What it is
error string    
error_description string    

410: result_expired.

Member Type Required What it is
error string    
error_description string    

GET /report-api/me

getMe

What the user menu draws

The path of the signed-in person’s own profile photo on this realm (#719), empty where they have none. It answers only about the token’s person.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: photo.

Member Type Required What it is
photo string   The path of the person’s own photo, or empty.

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

GET /report-api/openapi.json

getOpenApi

This document

The description of the released routes.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: This OpenAPI document.

Member Type Required What it is
components any JSON   The operations and components of an OpenAPI document are that specification’s vocabulary, not this API’s, and this document describes itself with them. The operations and components of an OpenAPI document are that specification’s vocabulary, not this API’s, and this document describes itself with them.
info object    
info.description string    
info.title string    
info.version string    
openapi string    
paths any JSON   The operations and components of an OpenAPI document are that specification’s vocabulary, not this API’s, and this document describes itself with them. The operations and components of an OpenAPI document are that specification’s vocabulary, not this API’s, and this document describes itself with them.

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

POST /report-api/queries

runQuery

Run a query

Synchronous when the source is bounded and the limit fits the sync caps. Otherwise 202 and a job. mode sync over the cap is result_too_large. A body over the byte cap or a sync call over the time cap is refused whole.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

Request body (optional)

Member Type Required What it is
aggregate one of count, null    
format one of json, csv, pdf    
groupBy list   The fields a count groups by, at most 8, each once.
groupBy[] string    
limit integer    
locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
mode one of auto, sync, async    
orderBy list   At most 8 entries, each a field and a direction, and a field once.
orderBy[].dir one of asc, desc yes  
orderBy[].field string yes  
select list   The fields, at most 64, each once. A count may name none, as three presets do.
select[] string    
source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
where (shape 1) object   and or or over between 1 and 16 filters.
where (shape 1).args list yes  
where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
where (shape 1).op one of and, or yes  
where (shape 2) object   not over one filter.
where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
where (shape 2).op one of not yes  
where (shape 3) object   isNull names the field and nothing else.
where (shape 3).field string yes  
where (shape 3).op one of isNull yes  
where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
where (shape 4).field string yes  
where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
where (shape 4).value string, or null, or number, or boolean yes  
where (shape 5) object   in, with between 1 and 50 values.
where (shape 5).field string yes  
where (shape 5).op one of in yes  
where (shape 5).value list yes  
where (shape 5).value[] string, or null, or number, or boolean    
where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
where (shape 6).field string yes  
where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.

200: The JSON, CSV or PDF body. JSON is an object with rows and truncated false. CSV is RFC 4180. PDF is PDF 1.4.

As application/json:

Member Type Required What it is
fields list    
fields[] string    
rows list    
rows[] map   One row: a field’s id to what it holds. The keys are the fields the query selected, and count where it counted.
rows[].{key} list, or string, or null, or number, or boolean    
rows[].{key}[] string, or null, or number, or boolean    
source string    
truncated boolean    

As application/pdf.

As text/csv.

202: A job was queued.

Member Type Required What it is
job object    
job.byteSize integer, or null    
job.completedAt string, or null    
job.definitionId string, or null    
job.definitionName string, or null    
job.error string, or null   The public error token. A job that exceeded report.asyncMaxMs carries result_too_large. The body of a failed job is not partial.
job.fields list    
job.fields[] string    
job.format string    
job.id string    
job.query object    
job.query.aggregate one of count, null    
job.query.format one of json, csv, pdf    
job.query.groupBy list   The fields a count groups by, at most 8, each once.
job.query.groupBy[] string    
job.query.limit integer    
job.query.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
job.query.mode one of auto, sync, async    
job.query.orderBy list   At most 8 entries, each a field and a direction, and a field once.
job.query.orderBy[].dir one of asc, desc yes  
job.query.orderBy[].field string yes  
job.query.select list   The fields, at most 64, each once. A count may name none, as three presets do.
job.query.select[] string    
job.query.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
job.query.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
job.query.where (shape 1) object   and or or over between 1 and 16 filters.
job.query.where (shape 1).args list yes  
job.query.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where (shape 1).op one of and, or yes  
job.query.where (shape 2) object   not over one filter.
job.query.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where (shape 2).op one of not yes  
job.query.where (shape 3) object   isNull names the field and nothing else.
job.query.where (shape 3).field string yes  
job.query.where (shape 3).op one of isNull yes  
job.query.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
job.query.where (shape 4).field string yes  
job.query.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
job.query.where (shape 4).value string, or null, or number, or boolean yes  
job.query.where (shape 5) object   in, with between 1 and 50 values.
job.query.where (shape 5).field string yes  
job.query.where (shape 5).op one of in yes  
job.query.where (shape 5).value list yes  
job.query.where (shape 5).value[] string, or null, or number, or boolean    
job.query.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
job.query.where (shape 6).field string yes  
job.query.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
job.query.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
job.queuedBecause one of every-person, asked, limit, source, run, schedule, null   Why this query is a job: every-person (an auto-mode query whose filter the directory cannot answer from an index, so it has to read every person), asked (mode async, or POST /jobs), limit (auto over report.syncMaxRows), source (a source that cannot be read synchronously), run (a saved definition run by hand) or schedule.
job.source string    
job.status one of queued, running, completed, failed, cancelled, expired    
job.submittedAt string, or null    

400: invalid_query, unknown_source is 404, unknown_field, unsupported_operation, unsupported_format or result_too_large.

Member Type Required What it is
error string    
error_description string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

429: too_many_jobs.

Member Type Required What it is
error string    
error_description string    

GET /report-api/realms

getRealms

The trust realms

The realm this request is in, and every realm with its id, name and path prefix where realms are active (null where they are not). The application draws its realm field and switch from it.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The realms.

Member Type Required What it is
current object    
current.id string    
current.name string    
current.prefix string   The realm’s path prefix; empty for the default realm.
realms list    
realms[].id string    
realms[].name string    
realms[].prefix string   The realm’s path prefix; empty for the default realm.

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

GET /report-api/schedules

getSchedules

The scheduled definitions and their runs

Every definition that carries a schedule, with when it next runs, the occurrence it last took, the notes a skipped run left, and its most recent scheduled jobs. A report:use token sees the definitions it owns or is shared; report:admin sees every one in the realm and may name one owner with owner (a urn:uuid subject or a username). A report:use token that names another owner is refused with forbidden (403). Paged; per is at most 100.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
owner query string    
page query integer    
per query integer    
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The schedules.

Member Type Required What it is
owner string, or null    
page integer    
pages integer    
per integer    
schedules list    
schedules[].definition object    
schedules[].definition.failures list    
schedules[].definition.failures[].at string, or null    
schedules[].definition.failures[].description string    
schedules[].definition.id string    
schedules[].definition.lastSlotAt string, or null    
schedules[].definition.name string    
schedules[].definition.nextRunAt string, or null    
schedules[].definition.notify boolean    
schedules[].definition.owner string    
schedules[].definition.ownerName string    
schedules[].definition.schedule string    
schedules[].definition.scheduleEnabled boolean    
schedules[].jobCount integer   How many scheduled jobs the definition has in all.
schedules[].jobs list   The most recent scheduled jobs, newest first, at most five.
schedules[].jobs[].byteSize integer, or null    
schedules[].jobs[].completedAt string, or null    
schedules[].jobs[].definitionId string, or null    
schedules[].jobs[].definitionName string, or null    
schedules[].jobs[].error string, or null   The public error token. A job that exceeded report.asyncMaxMs carries result_too_large. The body of a failed job is not partial.
schedules[].jobs[].fields list    
schedules[].jobs[].fields[] string    
schedules[].jobs[].format string    
schedules[].jobs[].id string    
schedules[].jobs[].query object    
schedules[].jobs[].query.aggregate one of count, null    
schedules[].jobs[].query.format one of json, csv, pdf    
schedules[].jobs[].query.groupBy list   The fields a count groups by, at most 8, each once.
schedules[].jobs[].query.groupBy[] string    
schedules[].jobs[].query.limit integer    
schedules[].jobs[].query.locale string, or null   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
schedules[].jobs[].query.mode one of auto, sync, async    
schedules[].jobs[].query.orderBy list   At most 8 entries, each a field and a direction, and a field once.
schedules[].jobs[].query.orderBy[].dir one of asc, desc yes  
schedules[].jobs[].query.orderBy[].field string yes  
schedules[].jobs[].query.select list   The fields, at most 64, each once. A count may name none, as three presets do.
schedules[].jobs[].query.select[] string    
schedules[].jobs[].query.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
schedules[].jobs[].query.where one of 6 shapes   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
schedules[].jobs[].query.where (shape 1) object   and or or over between 1 and 16 filters.
schedules[].jobs[].query.where (shape 1).args list yes  
schedules[].jobs[].query.where (shape 1).args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
schedules[].jobs[].query.where (shape 1).op one of and, or yes  
schedules[].jobs[].query.where (shape 2) object   not over one filter.
schedules[].jobs[].query.where (shape 2).arg object yes A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
schedules[].jobs[].query.where (shape 2).op one of not yes  
schedules[].jobs[].query.where (shape 3) object   isNull names the field and nothing else.
schedules[].jobs[].query.where (shape 3).field string yes  
schedules[].jobs[].query.where (shape 3).op one of isNull yes  
schedules[].jobs[].query.where (shape 4) object   A comparison with one value: a string, a number, a boolean or null, which the field’s type then decides.
schedules[].jobs[].query.where (shape 4).field string yes  
schedules[].jobs[].query.where (shape 4).op one of eq, ne, lt, le, gt, ge, contains, startsWith yes  
schedules[].jobs[].query.where (shape 4).value string, or null, or number, or boolean yes  
schedules[].jobs[].query.where (shape 5) object   in, with between 1 and 50 values.
schedules[].jobs[].query.where (shape 5).field string yes  
schedules[].jobs[].query.where (shape 5).op one of in yes  
schedules[].jobs[].query.where (shape 5).value list yes  
schedules[].jobs[].query.where (shape 5).value[] object   Nested deeper than this page draws.
schedules[].jobs[].query.where (shape 6) object   A comparison whose value is a saved definition’s parameter, named here and given when the definition runs.
schedules[].jobs[].query.where (shape 6).field string yes  
schedules[].jobs[].query.where (shape 6).op one of eq, ne, lt, le, gt, ge, contains, startsWith, in yes  
schedules[].jobs[].query.where (shape 6).param string yes The parameter’s name, 1 to 64 characters, as a parameter bag’s names are.
schedules[].jobs[].queuedBecause one of every-person, asked, limit, source, run, schedule, null   Why this query is a job: every-person (an auto-mode query whose filter the directory cannot answer from an index, so it has to read every person), asked (mode async, or POST /jobs), limit (auto over report.syncMaxRows), source (a source that cannot be read synchronously), run (a saved definition run by hand) or schedule.
schedules[].jobs[].source string    
schedules[].jobs[].status one of queued, running, completed, failed, cancelled, expired    
schedules[].jobs[].submittedAt string, or null    
scope one of mine, realm    
total integer    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: Another owner was named without report:admin.

Member Type Required What it is
error string    
error_description string    

GET /report-api/signals

getSignals

This application’s Shared Signals inbox

The CAEP and RISC events this application’s own stream delivered in this realm, newest first, twenty a page by default (#1042). report:admin sees every one (scope realm); anybody else sees only the events about themselves (scope own), and an application sees none. Each row says what this application did with it: the sessions it ended and the tokens of its own client it revoked for the person named, or why it did nothing. receiving is false, with why, when nothing can arrive. per is at most 100.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
page query integer    
per query integer    
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: One page of the inbox.

Member Type Required What it is
page integer    
pages integer    
per integer    
receiving boolean    
rows list    
rows[].at string    
rows[].name string    
rows[].reactions list    
rows[].reactions[].ended number    
rows[].reactions[].failed boolean    
rows[].reactions[].observed boolean    
rows[].reactions[].revoked number    
rows[].reactions[].skipped string   Why nothing was done, or empty.
rows[].subject string    
rows[].type string    
rows[].verified boolean    
rows[].vocabulary string    
scope one of realm, own    
total integer    
why list   Why nothing can arrive, where nothing can.
why[] string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string