Usage Data Via the API

You can track and report content consumption programmatically via the Cashmere API, enabling you to submit usage data for license compliance and retrieve detailed consumption insights.

All reporting API endpoints require Bearer token authentication. Include your API key in the Authorization header of each request. You can receive yours in the Console

Overview

The Reporting API allows you to:

  • Submit usage reports to comply with license rights obligations
  • Retrieve detailed consumption data with flexible filtering
  • Get usage summaries for dashboards and billing
  • Switch between consumer and publisher perspectives

Important: Use the view parameter to control whose consumption you're tracking: consumer (content you consumed) or publisher (consumption of your published content).

API Reference

Omnipub API

Common Workflows

Track your monthly consumption costs

  1. Get the summary for the current month: GET /report/summary
  2. Multiply tokens_consumed by your collection rate to estimate costs
  3. Review embeddings_count to understand what content drives usage

Audit consumption by specific content

  1. Find all usage of a specific external ID: GET /report?external_ids=article-123
  2. Review the billed_dollar_consumption field to see total costs
  3. Check license_right to see how the content was used

Generate a monthly compliance report

  1. Get detailed records for the month: GET /report?start_date=2026-01-01&end_date=2026-01-31&limit=100
  2. Filter by license right if needed: add &license_right=STORAGE
  3. Export results and paginate using offset for records beyond the first page

Supercharge your API usage

  1. Build automated billing dashboards - Pull monthly summaries with GET /report/summary, combine with your collection rates, and pipe results into your analytics tool or billing system. Set up a cron job to run this on the first of each month, automatically generating usage invoices without manual intervention.
  2. Optimize pagination for large datasets - When pulling historical data, start with summaries to understand volume, then use date ranges to chunk detailed queries. For example, if you have 10,000 records for a year, request one month at a time with limit=100 rather than trying to paginate through the entire dataset.
  3. Track consumption by content type - Use the external_ids parameter to analyze which content drives the most consumption. If you notice certain articles or books consistently appear in reports, consider featuring them more prominently or negotiating better rates for those specific collections.