usage.get

What this credential has been doing

GET/usage

Operation: usage.get
MCP tool: usage_get

Public API calls over a window, by day and by operation, plus the video time the account spent in the same window. A key sees only its own calls; a signed-in person sees the whole account. Windows are inclusive of from and exclusive of to, default the last 30 days, and may span at most 92.

curl 'https://api.gogoscreen.com/api/v1/usage' \
  -H "Authorization: Bearer $GOGOSCREEN_API_KEY"

A request to this operation.

json

{
  "from": "2026-09-21T11:03:00.000Z",
  "to": "2026-09-21T11:04:00.000Z",
  "scope": "api_key",
  "requests": 1034,
  "byDay": [
    {
      "day": "2026-09-21",
      "requests": 1034,
      "errors": 364
    }
  ],
  "byOperation": [
    {
      "operation": "renders.get",
      "requests": 125,
      "errors": 14
    },
    {
      "operation": "renders.quote",
      "requests": 106,
      "errors": 87
    },
    {
      "operation": "renders.create",
      "requests": 103,
      "errors": 94
    },
    {
      "operation": "templates.create",
      "requests": 88,
      "errors": 58
    },
    {
      "operation": "renders.list",
      "requests": 47,
      "errors": 17
    },
    {
      "operation": "webhooks.create",
      "requests": 40,
      "errors": 24
    },
    {
      "operation": "account.me",
      "requests": 25,
      "errors": 0
    },
    {
      "operation": "catalog.voices.list",
      "requests": 25,
      "errors": 1
    },
    {
      "operation": "mcp.list",
      "requests": 21,
      "errors": 0
    },
    {
      "operation": "storyboards.create",
      "requests": 20,
      "errors": 10
    },
    {
      "operation": "webhooks.list",
      "requests": 18,
      "errors": 2
    },
    {
      "operation": "marketing.exports.quote",
      "requests": 17,
      "errors": 8
    },
    {
      "operation": "marketing.sources.list",
      "requests": 17,
      "errors": 0
    },
    {
      "operation": "wallet.get",
      "requests": 16,
      "errors": 0
    },
    {
      "operation": "catalog.renderOptions",
      "requests": 15,
      "errors": 0
    },
    {
      "operation": "webhooks.delete",
      "requests": 15,
      "errors": 0
    },
    {
      "operation": "catalog.plans.list",
      "requests": 14,
      "errors": 0
    },
    {
      "operation": "mcp.initialize",
      "requests": 14,
      "errors": 0
    },
    {
      "operation": "storyboards.list",
      "requests": 14,
      "errors": 0
    },
    {
      "operation": "templates.delete",
      "requests": 14,
      "errors": 0
    },
    {
      "operation": "templates.list",
      "requests": 14,
      "errors": 0
    },
    {
      "operation": "wallet.ledger.list",
      "requests": 14,
      "errors": 0
    },
    {
      "operation": "catalog.marketing.templates.list",
      "requests": 13,
      "errors": 1
    },
    {
      "operation": "marketing.brandKit.get",
      "requests": 13,
      "errors": 0
    },
    {
      "operation": "marketing.exports.list",
      "requests": 13,
      "errors": 0
    },
    {
      "operation": "marketing.generations.list",
      "requests": 13,
      "errors": 0
    },
    {
      "operation": "marketing.projects.list",
      "requests": 13,
      "errors": 0
    },
    {
      "operation": "renders.cancel",
      "requests": 13,
      "errors": 3
    },
    {
      "operation": "usage.get",
      "requests": 13,
      "errors": 0
    },
    {
      "operation": "webhooks.update",
      "requests": 13,
      "errors": 0
    },
    {
      "operation": "templates.get",
      "requests": 12,
      "errors": 1
    },
    {
      "operation": "templates.update",
      "requests": 12,
      "errors": 0
    },
    {
      "operation": "webhooks.deliveries.list",
      "requests": 12,
      "errors": 1
    },
    {
      "operation": "webhooks.get",
      "requests": 12,
      "errors": 1
    },
    {
      "operation": "webhooks.test",
      "requests": 12,
      "errors": 0
    },
    {
      "operation": "storyboards.get",
      "requests": 11,
      "errors": 0
    },
    {
      "operation": "marketing.brandKit.put",
      "requests": 9,
      "errors": 8
    },
    {
      "operation": "storyboards.cancel",
      "requests": 9,
      "errors": 1
    },
    {
      "operation": "marketing.sources.create",
      "requests": 8,
      "errors": 8
    },
    {
      "operation": "mcp.prompts.list",
      "requests": 8,
      "errors": 0
    },
    {
      "operation": "mcp.resources.read",
      "requests": 8,
      "errors": 0
    },
    {
      "operation": "marketing.projects.create",
      "requests": 7,
      "errors": 7
    },
    {
      "operation": "marketing.generations.get",
      "requests": 6,
      "errors": 6
    },
    {
      "operation": "marketing.sources.get",
      "requests": 6,
      "errors": 6
    },
    {
      "operation": "mcp.resources.list",
      "requests": 6,
      "errors": 0
    },
    {
      "operation": "renders.download",
      "requests": 6,
      "errors": 2
    },
    {
      "operation": "keys.list",
      "requests": 3,
      "errors": 3
    },
    {
      "operation": "marketing.projects.get",
      "requests": 1,
      "errors": 1
    }
  ],
  "secondsCharged": 58,
  "details": null
}

200 response, captured from a real call. Ids, timestamps and signed URLs are replaced; the shape is untouched.

At a glance

Fact	Detail
Scopes	`usage:read`
Credentials	a signed in dashboard session or an API key.
Rate limit	600 requests a minute per credential, in the `read` class.
Idempotency	Not applicable. This operation changes nothing.
MCP tool	`usage_get`
Always sets	`Cache-Control: private, no-store`

Query parameters

Name	Type	Required	Description
from	string	Optional	The start of the window, inclusive. Defaults to 30 days ago.format: date-time
to	string	Optional	The end of the window, exclusive. Defaults to now.format: date-time
groupBy	string	Optional	Which breakdowns to compute. `both` is the default.Default `"both"`one of: day, operation, both

Response

Answers 200. Every answer also carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and every error body carries a requestId.

200 OK

What this credential has been doing

200 OK body
Name	Type	Description
byDay	object[]	UTC days, ascending. Absent days are absent, not zero.
day	string
errors	number
requests	number
byOperation	object[]	Busiest first.
errors	number
operation	string
requests	number
details	object \| null	Present only when a field above could not be answered, saying which and why.
note	string
from	string	format: date-time
requests	number	Every public call in the window, whatever it answered.
scope	string	`api_key` when a key asked — it sees only its own calls.one of: api_key, account
secondsCharged	number \| null	Video time charged in the window, from the wallet ledger — the only authority on spend. For a signed-in person this is the ACCOUNT's total. For a KEY it is the total of the work THAT KEY created: renders and marketing exports it started, joined to the ledger by the row they were charged against. Work started in the dashboard is not a key's, and one key never sees another's.
to	string	format: date-time

200 OK headers
Header	Meaning
`Cache-Control`	Always `private, no-store`.

Errors

Every refusal is { error: { code, message, details?, requestId } }. Branch on code, never on the sentence. The full catalogue is at Errors.

Code	Status	When it happens	What to do
validation_failed	400	The merged path, query and body did not match the operation's schema. The schemas are strict, so an unknown field is a failure rather than something ignored, and a string carrying half of a character is refused before it can be stored.	Read `details.issues`. Each entry carries a `path`, a `message` and a machine readable `code`. Fix every named field and send the request again; the same body always fails the same way.
unauthorized	401	No credential was presented, or the key is unknown, revoked or expired, or an `X-API-Key` header carried something that is not an API key. `details.reason` says which.	Send `Authorization: Bearer gsk_live_…`. A revoked or expired key never starts working again, so issue a new one in the developer console. Put a dashboard session token in `Authorization`, never in `X-API-Key`.
forbidden_scope	403	The credential does not carry every scope the operation declares, or it is the wrong kind of credential for it. `keys.` and `assistant.` are user only and can never be called by a key.	`details.requiredScopes` and `details.missingScopes` name what is missing. A key's scopes cannot be changed after it is issued, so create a new key with them. When `details.allowedActors` is present, no key can call this operation at all.
not_found	404	No resource of that id belongs to this account. A resource that belongs to somebody else answers 404 as well, never 403.	Check the id. Do not treat this as a permissions problem.
rate_limited	429	The credential's per minute budget, the account's per minute ceiling, or a daily cap was exceeded. `details.scope` is `minute`, `day` or `account`, or `global` when the product's own daily cap on voice previews is spent.	Wait the `Retry-After` seconds and retry. `details.limit` and `details.resetAt` say what was hit and when it reopens. The `RateLimit-*` headers on every answer let a client pace itself before it gets here.
internal_error	500	An unhandled failure inside this API. The original message is logged and never answered.	Retry once, then quote `requestId` to support. A 5xx deletes the idempotency claim rather than storing it, so retrying under the same key is safe.