Reference

Get account usage

GET /v1/account/usage. Credits charged, refunded and added in a period, by action and by key.

Generated from the contractsView as Markdown

GET /v1/account/usage

Credits charged, refunded and added in a period, by action and by key.

Property	Value
Endpoint	`GET https://mydatahub.emailmovers.com/v1/account/usage`
Operation id	`getAccountUsage`
Cost	Free (0 credits)
Access	An API key or an OAuth 2.1 token with the scope `account:read`.
Tag	Account

Request

Parameters

Name	In	Type	Required	Description
`from`	query	string (date)	no	First day, inclusive. Default 30 days ago.
`to`	query	string (date)	no	Last day, inclusive. Default today.
`MyDataHub-Version`	header	string	no	The dated API version, pinned per key when left out. Non-breaking changes ship as new dates; the path major changes only for breaking changes, with a 12 month deprecation window.

Example request

curl "https://mydatahub.emailmovers.com/v1/account/usage" \
  -H "Authorization: Bearer $MYDATAHUB_API_KEY"

Responses

200: Usage in the period.

Headers: RateLimit, RateLimit-Policy.

Member	Type	Always present	Description
`from`	string (date)	yes
`to`	string (date)	yes
`credits_charged`	number (0 or more)	yes	Credits, to one decimal place: whole at 1 credit a record, fractional only where a rule is (0.1 company-only, 1.8 outright, both proposed).
`credits_refunded`	number (0 or more)	yes	Credits, to one decimal place: whole at 1 credit a record, fractional only where a rule is (0.1 company-only, 1.8 outright, both proposed).
`credits_added`	number (0 or more)	yes	Credits, to one decimal place: whole at 1 credit a record, fractional only where a rule is (0.1 company-only, 1.8 outright, both proposed).
`by_action`	array of object	yes
`by_action[].action`	string	yes
`by_action[].calls`	integer (0 or more)	yes
`by_action[].credits`	number (0 or more)	yes	Credits, to one decimal place: whole at 1 credit a record, fractional only where a rule is (0.1 company-only, 1.8 outright, both proposed).
`by_key`	array of object	yes
`by_key[].key_id`	string	yes	Format: an API key id: key_ followed by a 26 character ULID in upper case Crockford base32, such as key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA.
`by_key[].label`	string	yes
`by_key[].credits`	number (0 or more)	yes	Credits, to one decimal place: whole at 1 credit a record, fractional only where a rule is (0.1 company-only, 1.8 outright, both proposed).

Example response

{
  "from": "2026-09-01",
  "to": "2026-09-30",
  "credits_charged": 5400,
  "credits_refunded": 0,
  "credits_added": 6000,
  "by_action": [
    {
      "action": "count",
      "calls": 1840,
      "credits": 0
    },
    {
      "action": "record",
      "calls": 2,
      "credits": 5400
    }
  ],
  "by_key": [
    {
      "key_id": "key_01JB3Z9R6T1Y5W8ZAK8Q2V7XN3",
      "label": "SDR agent",
      "credits": 400
    }
  ]
}

Errors

Every error is a problem object with a code and a next_step. Every response carries the RateLimit and RateLimit-Policy headers; see Rate limits.

Status	Problem codes	When
400	`invalid-request`, `idempotency-key-required`, `unsupported-version`	The request could not be read, or an Idempotency-Key is missing.
401	`authentication-required`, `account-required`	Sign in (OAuth) or send an API key (authentication-required), or create a free account for what the anonymous tier does not cover (account-required).
403	`insufficient-scope`, `confirmation-required`, `business-details-required`, `licence-acceptance-required`, `dpa-acceptance-required`, `agent-budget-exceeded`	The token lacks a scope (insufficient-scope, with required_scope and a WWW-Authenticate step-up challenge); no person confirmed the spend and no agent key covers it (confirmation-required, with an approval_url); an agent key's per-order cap or monthly budget does not cover it (agent-budget-exceeded); an account made by self-serve sign-up has not yet confirmed its business name and that it is a UK business, which its first order needs (business-details-required); the order needs the Data Licence and Sharing Agreement accepted at the version in force (licence-acceptance-required); or a suppression upload comes before the organisation has accepted the Article 28 data processing agreement in force (dpa-acceptance-required). Nothing is charged.
422	`validation-failed`, `quote-required`, `dataset-unavailable`	The request is not valid. errors lists every problem with a JSON pointer and did_you_mean.
429	`rate-limited`	Too many requests. Wait for Retry-After.
Any other failure	`internal-error`, `service-unavailable`, `tps-screen-expired`	Something failed on our side (500 internal-error) or the service is briefly unavailable (503 service-unavailable, with Retry-After). Nothing was charged; retry with the same Idempotency-Key. A count, sample, quote or order with telephone in play is also refused with 503 tps-screen-expired, with no Retry-After, while the dataset version's TPS and CTPS screen is more than 28 days old.