Skip to main content
GET
Publisher usage
GET https://api-datahub.octoparse.com/v1/publisher/usage Authentication: API key required (Authorization: Bearer <API Key>). How your apps were called in a period: range totals, plus breakdowns by day (or hour for short ranges), app, and call channel (any two can be crossed), or diagnostic breakdowns by terminal state, version, or error code. This is the publisher-side counterpart of billing aggregation: the same vocabulary (created_from / created_to keyed by run start time, start inclusive and end exclusive; tz_offset only moves day boundaries; data_app / triggered_by narrow the scope), with ownership flipped from “runs I started” to “apps I own” (including apps with zero releases). Day / hour / app / channel breakdowns come from hour buckets accumulated at terminal state, so any range and whole-hour offset stay exact and cheap. State / version / error breakdowns are computed on demand from run details, so both bounds are required and the span must be at most 92 days (400 range-too-wide). Error groups cover only runs that carry an error; each group includes the latest error message as sample_message. Author debug runs are excluded by default; platform health probes never count. Success includes partial success; cancelled runs stay out of the success-rate denominator; metrics with no terminal runs are null. amount is the data fee callers paid for these runs, not the publisher’s settled revenue. Day / hour groups ascend (hour keys are local clock YYYY-MM-DDTHH:00 under tz_offset, with no timezone suffix). Other groups descend by run count. Unknown or other people’s apps in data_app return 404. totals.callers is the distinct caller-user count in the range, from run details, and is set only when the range is bounded and at most 92 days. group_by=caller breaks down a single private or shared app by caller: the author (caller_kind=owner) and users currently on the grant list (grantee) show under their current username; everyone else (former grantees, callers from a public period) merges into one other group. Public apps or multiple apps return 400 caller-group-unavailable: public-app callers stay anonymous and are counted only.

Request

Query parameters

string
default:"day"
One or two dimensions, comma-separated: day / hour / data_app / triggered_by / state / version / error / caller (for example day,data_app). day and hour cannot combine; state / version / error / caller need a bounded range of at most 92 days; caller also requires exactly one private or shared app. Default day.
string[]
Limit to these apps (<username>/<app_name>, repeatable). Default: all of your apps.
string
Inclusive start.
string
Exclusive end.
integer
default:"0"
Timezone offset in minutes for day / hour buckets. Use 480 for China Standard Time. Buckets are hour-grained; half-hour offsets round to the hour.Range -720 to 840.
string
Limit to one call channel (api / sdk / mcp / web, and so on).
boolean
default:"False"
Whether to include author debug runs.
boolean
default:"False"
Also return previous_totals for the equal-length window immediately before created_from. Requires both bounds.

Example request

Response

200 success

The payload is wrapped in data. Fields:
object
required
The range and offset actually used.
string
Currency.
object
required
Range totals.
object
Equal-length prior-window totals when compare=true.
string
Dimension(s) actually used.
object[]
Group rows. Each row carries the same metrics as totals, plus dimension keys (day / hour / namespace + app_name / channel / state / version / error_code + error_category + sample_message + last_seen_at / username + caller_kind). Unused keys are null.

Errors

Error responses use {"error": {code, category, message, retryable}}. See Errors.

Client libraries

The Python and JavaScript SDKs do not wrap this endpoint yet. Call REST directly.