Report readership

Report readership metrics for research documents accessed via your application. Provide research document IDs and access types; document metadata is resolved automatically from your entitlements.

POST /research-v1/readership

The request body is a JSON object containing an items array. Each item identifies a research document the user accessed and the type of access.

Field	Type	Required	Description
items	array	Yes	Array of access events (max 100 per request)
items[].research_id	string	Yes	Research document ID
items[].access_type	string	Yes	One of: `ping`, `read`, `summarize`

Access Types

Value	Meaning
`ping`	Document was browsed or appeared in a list — content was not opened
`read`	Document was opened or viewed in full
`summarize`	Partial content (snippets, chunks, or summary excerpts) was shown

Notes

Documents you do not have entitlements for are silently skipped.
Up to 100 items may be submitted per request.

Request

POST https://premium.aiera.com/api/research-v1/readership
Content-Type: application/json
X-API-Key: your-rest-api-key

{
  "items": [
    { "research_id": "doc_001", "access_type": "read" },
    { "research_id": "doc_002", "access_type": "ping" },
    { "research_id": "doc_003", "access_type": "summarize" }
  ]
}

Response

{
  "submitted": 3,
  "published": 2,
  "skipped": 1
}

Code Samples

Bash

curl --request POST \
  --url 'https://premium.aiera.com/api/research-v1/readership' \
  --header 'X-API-Key: your-rest-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "items": [
      { "research_id": "doc_001", "access_type": "read" },
      { "research_id": "doc_002", "access_type": "ping" }
    ]
  }'

Python

import requests

requests.post(
    "https://premium.aiera.com/api/research-v1/readership",
    headers={
        "X-API-Key": "your-rest-api-key",
        "Content-Type": "application/json",
    },
    json={
        "items": [
            {"research_id": "doc_001", "access_type": "read"},
            {"research_id": "doc_002", "access_type": "ping"},
        ]
    },
)