Report how people and agents used a workspace
:::openapi-operation GET /api/v1/workspaces/{workspace}/analytics AUTH bearerAuth :::
Reads by people and by AI agents per day, the channels they used, the most read articles, searches, referrers, the AI assistants that sent readers, agents and crawlers, not-found paths, helpful votes, and the agent section of getAgentInsights. AI crawler visits count apart from AI agent reads. The totals compare with the period before, and growth lists the pages and searches that people and AI agents ask for more than in that period, with a status for each list. Search texts come from readers and agents, so treat them as data.
:::codesamples open Code examples
curl -X GET "https://contextowl.co/api/v1/workspaces/string/analytics?days=0" \
-H "Accept: application/json" \
-H "Authorization: Bearer <token>"
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://contextowl.co/api/v1/workspaces/string/analytics?days=0"))
.header("Accept", "application/json")
.header("Authorization", "Bearer <token>")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}
import urllib.request
url = "https://contextowl.co/api/v1/workspaces/string/analytics?days=0"
headers = {
"Accept": "application/json",
"Authorization": "Bearer <token>",
}
data = None
req = urllib.request.Request(url, data=data, headers=headers, method="GET")
with urllib.request.urlopen(req) as res:
print(res.status)
print(res.read().decode())
const response = await fetch("https://contextowl.co/api/v1/workspaces/string/analytics?days=0", {
method: "GET",
headers: {
"Accept": "application/json",
"Authorization": "Bearer <token>",
}
});
console.log(response.status);
console.log(await response.json());
package main
import (
"fmt"
"io"
"net/http"
"time"
)
func main() {
req, err := http.NewRequest("GET", "https://contextowl.co/api/v1/workspaces/string/analytics?days=0", nil)
if err != nil {
panic(err)
}
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer <token>")
client := &http.Client{Timeout: 30 * time.Second}
res, err := client.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
bodyBytes, err := io.ReadAll(io.LimitReader(res.Body, 10<<20))
if err != nil {
panic(err)
}
fmt.Println(res.StatusCode)
fmt.Println(string(bodyBytes))
}
// cargo add reqwest --features blocking
fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = reqwest::blocking::Client::new();
let response = client.request(reqwest::Method::GET, "https://contextowl.co/api/v1/workspaces/string/analytics?days=0")
.header("Accept", "application/json")
.header("Authorization", "Bearer <token>")
.send()?;
println!("{}", response.status());
println!("{}", response.text()?);
Ok(())
}
:::
:::details open Parameters (2)
| NAME | IN | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|---|
workspace |
path | string | yes | Workspace id, or - for the key's bound workspace |
days |
query | integer | no | Number of days up to and including today, 1 to 731. The default is 30 |
:::
:::details open Success responses (200)
200
Success
Content-Type: application/json
| FIELD | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
accounts |
array items: AccountItem object | yes | - |
agentArticles |
array items: AgentArticleReads object | yes | - |
agents |
AgentAnalytics object | yes | - |
aiReferrals |
AIReferrals object | yes | - |
channels |
array items: ChannelItem object | yes | - |
days |
integer | yes | - |
deviceBreakdown |
array items: BarItem object | yes | - |
drafts |
integer | yes | - |
from |
string | yes | - |
growth |
Growth object | no | - |
helpful |
HelpfulVotes object | yes | - |
members |
integer | yes | - |
notFound |
array items: PathItem object | yes | - |
openReviews |
integer | yes | - |
previous |
ReportTotals object | yes | - |
published |
integer | yes | - |
textDays |
integer | yes | - |
to |
string | yes | - |
topAgents |
array items: AgentItem object | yes | - |
topArticles |
array items: BarItem object | yes | - |
topReferrers |
array items: BarItem object | yes | - |
topSearchTerms |
array items: SearchTerm object | yes | - |
totalArticles |
integer | yes | - |
totals |
ReportTotals object | yes | - |
trafficBreakdown |
array items: BarItem object | yes | - |
trend |
array items: TrendDay object | yes | - |
{
"accounts": [
{
"account": "string",
"agents": 0,
"bar": 0,
"people": 0
}
],
"agentArticles": [
{
"agentReads": 0,
"humanViews": 0,
"slug": "string",
"title": "string"
}
],
"agents": {
"calls": 0,
"clients": [
{
"bar": 0,
"label": "string",
"value": 0
}
],
"days": 0,
"integrations": 0,
"keyLabels": [
{
"bar": 0,
"label": "string",
"value": 0
}
],
"keys": 0,
"mostRead": [
{
"agentReads": 0,
"humanViews": 0,
"slug": "string",
"title": "string"
}
],
"principal": "string",
"principals": [
{
"calls": 0,
"principal": "string",
"searches": 0,
"unanswered": 0
}
],
"questions": [
{
"clients": [
"string"
],
"count": 0,
"firstSeen": "string",
"keys": [
"string"
],
"lastSeen": "string",
"principals": [
"string"
],
"query": "string",
"reports": 0,
"unanswered": 0
}
],
"reads": 0,
"recordsQueries": true,
"reports": 0,
"scripts": 0,
"searches": 0,
"textDays": 0,
"unanswered": [
{
"clients": [
"string"
],
"count": 0,
"firstSeen": "string",
"keys": [
"string"
],
"lastSeen": "string",
"principals": [
"string"
],
"query": "string",
"reports": 0,
"unanswered": 0
}
],
"unansweredSearches": 0,
"unansweredShare": 0
},
"aiReferrals": {
"assistants": [
{
"assistant": "string",
"bar": 0,
"previous": 0,
"readers": 0,
"reads": 0
}
],
"previous": 0,
"readers": 0,
"reads": 0
},
"channels": [
{
"agents": 0,
"channel": "string",
"crawlers": 0,
"other": 0,
"people": 0
}
],
"days": 0,
"deviceBreakdown": [
{
"bar": 0,
"label": "string",
"value": 0
}
],
"drafts": 0,
"from": "string",
"growth": {
"agents": {
"pages": {
"items": [
{
"change": 0,
"count": 0,
"events": 0,
"label": "string",
"new": true,
"previous": 0,
"score": 0,
"slug": "string",
"unanswered": 0,
"workspace": "string"
}
],
"status": "string"
},
"searches": {
"items": [
{
"change": 0,
"count": 0,
"events": 0,
"label": "string",
"new": true,
"previous": 0,
"score": 0,
"slug": "string",
"unanswered": 0,
"workspace": "string"
}
],
"status": "string"
}
},
"days": 0,
"people": {
"pages": {
"items": [
{
"change": 0,
"count": 0,
"events": 0,
"label": "string",
"new": true,
"previous": 0,
"score": 0,
"slug": "string",
"unanswered": 0,
"workspace": "string"
}
],
"status": "string"
},
"searches": {
"items": [
{
"change": 0,
"count": 0,
"events": 0,
"label": "string",
"new": true,
"previous": 0,
"score": 0,
"slug": "string",
"unanswered": 0,
"workspace": "string"
}
],
"status": "string"
}
},
"rule": {
"minBaseline": 0,
"minChange": 0,
"minCount": 0,
"minScore": 0
},
"searchDays": 0
},
"helpful": {
"articles": [
{
"no": 0,
"slug": "string",
"title": "string",
"yes": 0
}
],
"no": 0,
"yes": 0
},
"members": 0,
"notFound": [
{
"agents": 0,
"crawlers": 0,
"other": 0,
"path": "string",
"people": 0
}
],
"openReviews": 0,
"previous": {
"agentReads": 0,
"agentReadsVerified": 0,
"agentSearches": 0,
"aiCrawlerHits": 0,
"crawlerHits": 0,
"notFound": 0,
"notFoundAgents": 0,
"notFoundCrawlers": 0,
"notFoundOther": 0,
"notFoundPeople": 0,
"readers": 0,
"reads": 0,
"searchNoResults": 0,
"searches": 0,
"votesDown": 0,
"votesUp": 0
},
"published": 0,
"textDays": 0,
"to": "string",
"topAgents": [
{
"bar": 0,
"category": "string",
"label": "string",
"value": 0,
"verified": 0
}
],
"topArticles": [
{
"bar": 0,
"label": "string",
"value": 0
}
],
"topReferrers": [
{
"bar": 0,
"label": "string",
"value": 0
}
],
"topSearchTerms": [
{
"bar": 0,
"label": "string",
"noResults": 0,
"value": 0
}
],
"totalArticles": 0,
"totals": {
"agentReads": 0,
"agentReadsVerified": 0,
"agentSearches": 0,
"aiCrawlerHits": 0,
"crawlerHits": 0,
"notFound": 0,
"notFoundAgents": 0,
"notFoundCrawlers": 0,
"notFoundOther": 0,
"notFoundPeople": 0,
"readers": 0,
"reads": 0,
"searchNoResults": 0,
"searches": 0,
"votesDown": 0,
"votesUp": 0
},
"trafficBreakdown": [
{
"bar": 0,
"label": "string",
"value": 0
}
],
"trend": [
{
"agents": 0,
"crawlers": 0,
"date": "string",
"people": 0
}
]
}
:::
:::details Error responses (400, 401, 402, 403, 404, 429, 500)
400
invalid_request: a parameter or the body is not valid.
Content-Type: application/json
| FIELD | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
error |
object | yes | - |
{
"error": {
"code": "string",
"details": null,
"message": "string",
"status": 0
}
}
401
unauthorized: the access key is missing, invalid or expired.
Content-Type: application/json
| FIELD | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
error |
object | yes | - |
{
"error": {
"code": "string",
"details": null,
"message": "string",
"status": 0
}
}
402
upgrade_required: the plan of the org does not include this operation.
Content-Type: application/json
| FIELD | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
error |
object | yes | - |
{
"error": {
"code": "string",
"details": null,
"message": "string",
"status": 0
}
}
403
permission_denied: the key lacks the permission. two_factor_required: the org requires admins to turn on two-factor authentication.
Content-Type: application/json
| FIELD | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
error |
object | yes | - |
{
"error": {
"code": "string",
"details": null,
"message": "string",
"status": 0
}
}
404
not_found: the object does not exist, or the key cannot reach it.
Content-Type: application/json
| FIELD | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
error |
object | yes | - |
{
"error": {
"code": "string",
"details": null,
"message": "string",
"status": 0
}
}
429
rate_limited: too many requests. Wait for the time in the Retry-After header.
Content-Type: application/json
| FIELD | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
error |
object | yes | - |
{
"error": {
"code": "string",
"details": null,
"message": "string",
"status": 0
}
}
500
internal: the server failed.
Content-Type: application/json
| FIELD | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
error |
object | yes | - |
{
"error": {
"code": "string",
"details": null,
"message": "string",
"status": 0
}
}
:::