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
  }
}

:::