The API can provide a mechanism to query the reporting data. This gives a flat report in CSV format you can use in other analysis tools such as Tableau, Power BI and others.
- The optional reports API functionality to be enabled for your organisation - your account manager will be happy to discuss pricing with you
- An API Key from the domain organisation or sub-organisation the reports will cover
- A basic practical knowledge of APIs and coding
Perform a GET request to the following URL:
Where example.org is your OpenAthens API name and:
|Parameter||Required||Accepted values||Default if omitted|
(other report types will be added in the future)
|from||Y||yyyy-MM (default if no granularity is set)|
|to||Y||yyyy-MM (default if no granularity is set)|
Specify a single resource by entityID
Can not be used with
All includes all the sub-organisations below the authenticated user
|The organisation of the authenticated user|
Optional. Can only be used with
If Hourly or Daily: 'from' and 'to' date format should be yyyy-MM-ddTHH:mm
If Monthly: 'from' and 'to' date format can be yyyy-MM
The maximum date range you can query depends on the granularity, as follows:
|Granularity||Maximum date range||Example|
Provides the week from 1 April 2020 07:00 UTC through 7 April 2020 06:00 UTC
Provides the month from 1 April 2020 through 30 April 2020
Provides the 12 months from April 2019 through March 2010
HTTP Response Code
The request was successful
|400||Bad request - e.g. date out of range|
The requester does not have permission to perform this operation
Since reports can take some time to run, the response is an
application/vnd.eduserv.iam.reports.task-v1+json object containing a href to the task status. Your application will need to monitor this until the task completes (20s is a reasonable wait time to code).
Once the task is complete, the object will have a status of FINISHED and a percentComplete of 100, and a link to the report.
When finished the response will have updated to include a link to the report
The downloaded report will be a CSV file with the headings:
Domain,Organisation number,Organisation name,DateTime,<by>,[<andyby>,]Count
Domainis your API name (as per the request). This will be constant for the report
Organisation numberis the numeric identifier of the organisation (or sub-organisations where scope=ALL_ORGANISATIONS in the request). See below if you have more than one in the report.
DateTimeis the date/time of the record as yyyy-MM for monthly granularity, yyyy-MM-dd for daily, and yyyy-MM-ddTHH:mmZ for hourly
<by>will be replaced by RESOURCE, GROUPS, PERMISSION_SETS, or ATTRIBUTE:<targetname> as per the request
<andBy>(where present) will similarly be replaced by the secondary breakdown identifier
Countwill be the number of transfers
All organisations and sub-organisations have a numeric identifier in the system whether or not they are marked as having a unique identifier - it's just not easy to see those identifiers in the interface for the ones who don't have the unique setting. Most don't need it, and turning it on can affect access to content.
This numeric identifier is persistent and will allow you to link stats from the same sub-organisations even if their name changes.
Reports are type:
Daily granularity reports are inclusive of the start and end date
Querying certain dates will produce an error:
- dates before your organisation joined OpenAthens
- dates before January 2018
- dates more than 48 months in the past