Skip to main content

​
Endpoint

GET /data/dashboard/telemetry
Use this endpoint to power customer-facing management dashboards. It returns scoped usage telemetry for credits spent, pages processed, extraction volume, processing status, review activity, token usage, credit balance, active users, active API keys, and time-series breakdowns.

​
Authentication

​
X-API-Key
string
required
API key with the usage:read scope.

​
Access Scope

The endpoint automatically scopes results based on the authenticated user:
CallerDefault scope
Project memberActive project only
Organization adminEntire organization
Platform adminPlatform-wide unless filters are provided
Regular project members cannot request telemetry for a project other than their active project.

​
Query Parameters

​
organization_id
string
Organization UUID. Non-admin users can only request their own organization.
​
project_id
string
Project UUID. Organization admins can request any project in their organization; regular members can only request their active project.
​
user_id
string
User UUID. Platform admin only.
​
days
integer
default:"30"
Relative lookback window when start_date is omitted. Range: 1 to 3660.
​
start_date
string
Inclusive ISO 8601 start timestamp.
​
end_date
string
Inclusive ISO 8601 end timestamp. Defaults to the current time.
​
group_by
string
default:"day"
Time-series grouping. Options: day, week, month.

​
Response Shape

​
scope
object
Resolved telemetry scope: platform, organization, project, or user.
​
period
object
Resolved date range and time-series grouping.
​
summary
object
Top-line metrics for documents, credits, pages, tokens, reviews, activity, credit balance, and processing time.
​
timeseries
array
Per-period counts for extraction records, completed/failed/pending records, charged documents, pages, credits, and tokens.
​
breakdowns
object
Breakdowns by status, project, and model/cost tier.
​
data_quality
object
Coverage and deduplication metadata, including processing-time coverage.

​
Example

curl "https://api.documind.cloud/api/v1/data/dashboard/telemetry?days=30&group_by=day" \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "scope": {
    "type": "organization",
    "organization_id": "22222222-2222-2222-2222-222222222222",
    "project_id": null,
    "user_id": null
  },
  "summary": {
    "documents": {
      "extraction_records": 5619,
      "charged_documents": 5473,
      "completed_records": 5473,
      "failed_records": 146,
      "pending_records": 0,
      "success_rate_percentage": 97.4,
      "failure_rate_percentage": 2.6
    },
    "credits": {
      "spent": 64836,
      "extraction": 64821,
      "citation_matching": 15,
      "average_per_charged_document": 11.85,
      "average_per_page": 10.15
    },
    "pages": {
      "processed": 6390,
      "average_per_charged_document": 1.17
    },
    "tokens": {
      "used": 94355452
    }
  },
  "timeseries": [
    {
      "period": "2026-07-07",
      "extraction_records": 30,
      "completed_records": 30,
      "failed_records": 0,
      "pending_records": 0,
      "charged_documents": 30,
      "pages_processed": 31,
      "credits_spent": 310,
      "tokens_used": 450000
    }
  ]
}

​
Notes

  • Credit spend is calculated from debit transactions joined to extraction records by document_id.
  • processing_time_seconds is stored for newly created extraction records. Historical rows may appear under missing_records.
  • Use short caching windows for customer dashboards to avoid repeatedly aggregating the same range.

​
Next Steps

List Extractions

Query extraction history and review state.

Usage Summary

Retrieve user-level usage totals.