Reference

Account and balance

get_account: Returns the organisation's credit balance by source, plan, per-action prices and rate limit, and for an agent key its monthly budget and per-order cap.

Generated from the contractsView as Markdown

Returns the organisation's credit balance by source, plan, per-action prices and rate limit, and for an agent key its monthly budget and per-order cap. Use it before quoting a large order, or when a spend is refused, to see what remains. Free; it needs a token with account:read. Top-ups happen on mydatahub.emailmovers.com, never inside a tool. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.

Property	Value
Tool name	`get_account`
Position in tools/list	2 of 22
Cost	Free
Scope	`account:read`
Annotations	readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false
Kind	Read only; idempotent, not destructive, closed world
REST equivalent	`GET /v1/account`

Input

This tool takes no arguments. The schema sets additionalProperties to false, so any member is refused.

Example call

The params of a tools/call request:

{
  "name": "get_account",
  "arguments": {}
}

Output

The result carries structuredContent that matches this schema, and one line of text that leads with the number.

Member	Type	Always present	Description
`organisation`	object	yes
`organisation.id`	string	yes	Format: an organisation id: org_ followed by a 26 character ULID in upper case Crockford base32, such as org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8.
`organisation.name`	string	yes
`organisation.business_details`	`BusinessDetails`	yes	Whether the business name and a UK business confirmation are on record, which a self-serve account needs before its first order.
`user`	object or null	yes	The signed-in person; null when the caller is an API key.
`user.id`	string	yes	Format: a user id: usr_ followed by a 26 character ULID in upper case Crockford base32, such as usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8.
`user.name`	string	yes
`mode`	enum: `live`, `test`	yes	live keys (mdh_live_) spend real credits; test keys (mdh_test_) return synthetic data and never charge.
`plan`	object	yes
`plan.id`	string	yes
`plan.name`	string	yes
`plan.kind`	enum: `free`, `subscription`, `pack`	yes
`plan.renews_at`	string (date) or null	yes
`plan.cancel_at_period_end`	boolean	yes
`balance`	object	yes	Credits by source.
`balance.credits`	number	yes	Credits available to spend now.
`balance.pack_credits`	number	yes	From credit packs: never expire.
`balance.subscription_credits`	number	yes	From the plan: roll over while subscribed, up to the cap.
`balance.rollover_cap`	integer (0 or more) or null	yes
`balance.low_threshold`	integer (0 or more) or null	yes	The credits.low webhook fires when the balance crosses this.
`prices`	array of `CreditRule`	yes	What each action costs in credits.
`prices[].action`	string	yes
`prices[].label`	string	yes
`prices[].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).
`prices[].unit`	enum: `call`, `record`, `match`	yes
`prices[].status`	enum: `confirmed`, `proposed`, `to_confirm`	yes	confirmed is in force; proposed awaits a decision; to_confirm is a figure still being checked.
`prices[].note`	string	no
`gbp_per_credit`	number (0 or more)	yes	Your plan's price per credit, excluding VAT.
`rate_limit`	`RateLimit`	yes	The caller's count limits and what remains in the window.
`rate_limit.tier`	enum: `anonymous`, `free`, `paid`	yes
`rate_limit.counts_per_minute`	integer (0 or more) or null	yes
`rate_limit.counts_per_hour`	integer (0 or more) or null	yes
`rate_limit.counts_per_day`	integer (0 or more) or null	yes
`rate_limit.remaining`	integer (0 or more)	yes
`rate_limit.resets_at`	string (date-time)	yes
`rate_limit.status`	enum: `confirmed`, `to_confirm`	yes
`key`	object or null	yes	The calling key and, for an agent key, its budget; null for a person.
`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.
`key.kind`	enum: `standard`, `agent`	yes
`key.budget`	`Budget` or null	yes
`key.per_order_max_credits`	integer (0 or more) or null	yes
`key.expires_at`	string (date-time) or null	yes
`account_manager`	object or null	yes	The named person behind Talk to us.
`account_manager.name`	string	yes
`account_manager.calendar_url`	string (uri)	yes
`agreements`	object	yes	The Data Licence and Sharing Agreement (accepted with every order, or with an agent key that orders on its own) and the Article 28 DPA (accepted with the first suppression list).
`agreements.dlsa`	`Agreement`	yes
`agreements.dpa`	`Agreement`	yes

Errors

A failed call returns isError true. The text content leads with the sentence a person acts on, then the whole problem as JSON, with code, detail, next_step and did_you_mean. A 401 and a step-up 403 are answered at HTTP level so the client can start authorisation. See Errors.