COUNTER reports from Research Connect

For libraries and publishers: what Research Connect reports about the AI usage of scholarly articles, how to harvest it, and how to ask for access.

What is reported

Research Connect reports AI usage only: the articles an AI assistant checked, asked for or received for its user. In COUNTER words that is Access_Method Agent.
There are three reports: the Platform Report (PR), the Title Report (TR) and the Item Report (IR). They are COUNTER release 5.1.1 JSON, by complete UTC month.
There are no Standard Views and no Database Report. Agent usage must not appear in a Standard View, so ours would always be empty. And we have no databases.

Put access_method=Agent in every report request.
Without it, every report comes back empty, with exception 3030, or with the 3031 or 3032 that already says why. That reads like a fault, and it is not one. We hold AI usage and nothing else, so a request that does not ask for it has nothing to report. Regular and TDM are accepted, and nothing is reported for them.

The base address is https://research-connect.oliveturn.com/counter. A harvester adds /r51/... to it: /r51/status, /r51/members, /r51/reports, and the reports /r51/reports/pr, /r51/reports/tr and /r51/reports/ir.
/r51/status needs no credential. It says whether the service is active.
The API reference lists every path, with its parameters and its answers.

Write to contact@oliveturn.com. Say whether you ask for a library, which is one institution, or for a publisher.
We then make a credential for that one institution or that one publisher: a requestor_id and an api_key. The key is shown once, when it is made. We keep only a hash of it, so we cannot show it again. A lost key is revoked, and a new one is made.
Both go in the query string of every request but /r51/status, as the COUNTER API defines. So treat the whole address of a request as a secret.

Your customer_id comes with your credential. A library has one: its own institution. A publisher starts with 0000000000000000, which is COUNTER's id for "The World".
/r51/members lists every customer id your credential may ask for. It needs a customer_id itself. Ask it with the customer id you were given.

A library sees its own institution's usage only. That is usage by readers whose browser is verified at the institution (an article has already arrived through its own sign-in), and usage that came through the institution's own network, when the institution publishes its IP ranges, no other institution's ranges hold the same address, and the institution is one that can be chosen at sign-in. An institution a reader only declared is never counted for a library.
A publisher sees all usage of its own articles, which COUNTER calls "The World". It can split that by institution with attributes_to_show=Institution_Name|Customer_ID, or ask for one institution at a time.
A library cannot ask for The World. A library never sees the usage of another institution, and a publisher never sees the usage of articles outside its own.

The four AI metrics of COUNTER's best practice for AI usage: Total_AI_Investigations, Unique_AI_Investigations, Total_AI_Requests and Unique_AI_Requests. A request with access_method=Agent and no metric_type carries these four.
A Unique_ number counts a user session once per article and day. A session counts twice on a day its scrambled key changes: when a reader pauses their history or the pause ends, when they clear it, when a code account becomes an email account or is merged into one, and, for an email account, once on the day this way of counting went live. ResearchConnect:AI_Conversations counts it twice too. The Total_ numbers do not change.
Our own numbers start with ResearchConnect: and appear only when metric_type names them: ResearchConnect:Total_AI_Denials, ResearchConnect:Unique_AI_Denials, ResearchConnect:Total_AI_Entitlement_Checks, ResearchConnect:Unique_AI_Entitlement_Checks and ResearchConnect:AI_Conversations. ResearchConnect:AI_Conversations is in the Platform Report only.
Our own columns appear only when attributes_to_show names them: ResearchConnect:AI_Client and ResearchConnect:Delivery_Route.
We hold no standard COUNTER metric. A metric_type that names one, such as Total_Item_Requests, is not carried, and the report says so with exception 3060.

One credential may make 30 requests a minute. More connections do not help: the count is per credential. Requests from one address are counted too, whatever the credential.
Every refusal is one COUNTER exception, in COUNTER JSON. An address that is not one of these paths answers 404. These are the exceptions a harvester will meet.
1010, "Service Busy" (HTTP 503). Other reports are being built, or this one took too long. Wait a minute and ask again, or ask for fewer months.
1020, "Client has made too many requests" (HTTP 429). Too many requests. Wait the number of seconds the Retry-After header gives.
1030, "Insufficient Information to Process Request" (HTTP 400). A required parameter is missing. The answer names each one.
2000, "Requestor Not Authorized to Access Service" (HTTP 401). The requestor_id is not known, or it was revoked. Check it, or write to us.
2010, "Requestor is Not Authorized to Access Usage for Institution" (HTTP 403). This credential may not see that customer_id. Ask /r51/members which ids it may see. A publisher that names an institution new to the record may have to wait a minute.
2020, "APIKey Invalid" (HTTP 401). The api_key does not match the requestor_id. Check it, or ask us for a new one.
3030, "No Usage Available for Requested Dates" (HTTP 200). No usage for those months. If the request has no access_method=Agent, add it, and ask again.

The reports are built to release 5.1.1 of the COUNTER Code of Practice, and our tests check them against COUNTER's own API file, COUNTER_API.json, with a small patch that adds the AI names it does not list yet, and our own names.
Research Connect is not registered with COUNTER yet, and COUNTER has not audited it.
Agent and the four AI metric names come from COUNTER's best practice for AI usage. COUNTER's API file does not list them yet, so a validator built from that file may reject them.

A report never holds a person or an account, and no usage in it has a time of day. Its header says only when the report was made. It counts articles, and conversations in the Platform Report, by month.
The privacy page says what the record behind the reports holds, and what it does not.

COUNTER asks us to say this: "This usage information is also available from the original publisher."
So the same usage may also reach a library in the publisher's own COUNTER reports. /r51/status carries the same notice in its Note.