Reference

Get order status

get_order: Returns one order's status (queued, building, verifying, ready, failed or cancelled), counts, charges, licence and links to its records, download and receipt, or the recent orders when order_id is left out.

Generated from the contractsView as Markdown

Returns one order's status (queued, building, verifying, ready, failed or cancelled), counts, charges, licence and links to its records, download and receipt, or the recent orders when order_id is left out. Use it after create_order to wait for ready, or rely on the order.ready webhook. Free; it needs orders:read. Call fetch_order_records once the status is ready. 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_order`
Position in tools/list	15 of 22
Cost	Free
Scope	`orders:read`
Annotations	readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false
Kind	Read only; idempotent, not destructive, closed world
REST equivalent	`GET /v1/orders/{id}`; `GET /v1/orders`

Input

The schema sets additionalProperties to false, so a member that is not listed is refused.

Member	Type	Required	Description
`order_id`	string	no	The order to return. Leave it out for the recent orders, newest first.
`status`	enum: `queued`, `building`, `verifying`, `ready`, `failed`, `cancelled`	no	queued, building, verifying, ready; failed if processing failed; cancelled (only while queued).
`limit`	integer (1 to 100)	no	Items per page, 1 to 100. Default 25. Default `25`.
`cursor`	string	no	An opaque cursor from next_cursor. Pass it back unchanged.

Example call

The params of a tools/call request:

{
  "name": "get_order",
  "arguments": {
    "order_id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E"
  }
}

Output

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

Order

Member	Type	Always present	Description
`id`	string	yes	Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.
`status`	enum: `queued`, `building`, `verifying`, `ready`, `failed`, `cancelled`	yes	queued, building, verifying, ready; failed if processing failed; cancelled (only while queued).
`name`	string	no
`quote_id`	string	yes	The machine quote the order settled.
`count_id`	string	yes	The count the machine quote was priced from.
`dataset_version`	string	no	The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.
`field_set`	string	no
`delivery`	array of enum: `api`, `csv`, `google_sheets`	no
`records`	integer (0 or more)	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_remaining`	number (0 or more)	yes	The balance right after this order was charged.
`cost_gbp`	number (0 or more)	yes	The charge in GBP excluding VAT at your plan's rate.
`licence_expires_at`	string (date) or null	yes	When the licence ends; null for outright ownership.
`licence`	`Licence`	yes	Licence terms as data, on every quote, order, records page and receipt. Records stay usable, pushable and re-downloadable free until reuse_until.
`licence.type`	enum: `multi_use_12m`, `outright`	yes	multi_use_12m (12 month multi-use, every plan) or outright (1.8 credits a record, proposed).
`licence.reuse_until`	string (date) or null	yes	Order date plus 12 months; null for outright.
`licence.resale_prohibited`	boolean	yes
`licence.permitted_channels`	array of enum: `email`, `telephone`, `post`	yes	email, telephone and post on standard terms.
`licence.warranty_url`	string (uri)	yes
`licence.terms_version`	string	yes	The version of the Data Licence and Sharing Agreement the licence is under, such as 1.0.
`licence.terms_url`	string (uri)	no	Where that version of the Data Licence and Sharing Agreement is published.
`confirmed_by`	`ConfirmedBy`	yes	Who approved the spend and from which client, recorded in the audit trail and on invoices.
`confirmed_by.method`	enum: `elicitation_form`, `approval_url`, `agent_key`, `app`	yes	elicitation_form (the MCP form), approval_url (the approval page's confirmation_token), agent_key (a pre-authorised agent key within its limits) or app (a person ordering in the app itself, a first-party session; third-party OAuth clients never count).
`confirmed_by.key_id`	string	no	The agent key, for agent_key.
`confirmed_by.user_id`	string	no	The person who confirmed.
`confirmed_by.client_id`	string	no	The OAuth client, such as a Client ID Metadata Document URL.
`confirmed_by.user_agent`	string or null	no	The calling client's User-Agent.
`confirmed_by.mtls_certificate_fingerprint`	string or null	no	SHA-256 of the client certificate when one was presented (ChatGPT's mTLS).
`confirmed_by.web_bot_auth_signature_agent`	string or null	no	The Signature-Agent of a verified Web Bot Auth signature, when present.
`confirmed_by.confirmed_at`	string (date-time)	no
`verification`	object	no	The real-time check at delivery, such as 4,102 checked, 4,071 passed.
`verification.checked`	integer (0 or more)	yes
`verification.passed`	integer (0 or more)	yes
`verification.replaced`	integer (0 or more)	yes
`records_url`	string (uri-reference)	yes	A path on https://mydatahub.emailmovers.com starting /v1/. Resolve it against the origin (RFC 3986), not by appending it to the server URL.
`download_url`	string (uri-reference)	no	302 to a single-use signed URL that lives 5 minutes.
`receipt_url`	string (uri-reference)	no	A path on https://mydatahub.emailmovers.com starting /v1/. Resolve it against the origin (RFC 3986), not by appending it to the server URL.
`validation_report`	`ValidationReportLinks`	no	Present once the order is ready.
`validation_report.pdf_url`	string (uri)	yes
`validation_report.json_url`	string (uri)	yes
`buyer_kit`	`BuyerKit`	no	Four signed documents that help the buyer use the list lawfully.
`buyer_kit.draft_lia_url`	string (uri)	yes
`buyer_kit.first_email_wording_url`	string (uri)	yes
`buyer_kit.article30_stub_url`	string (uri)	yes
`buyer_kit.due_diligence_file_url`	string (uri)	yes
`created_at`	string (date-time)	no
`ready_at`	string (date-time) or null	no
`failure`	string or null	no

OrderList

Member	Type	Always present	Description
`data`	array of `Order`	yes
`data[].id`	string	yes	Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.
`data[].status`	enum: `queued`, `building`, `verifying`, `ready`, `failed`, `cancelled`	yes	queued, building, verifying, ready; failed if processing failed; cancelled (only while queued).
`data[].name`	string	no
`data[].quote_id`	string	yes	The machine quote the order settled.
`data[].count_id`	string	yes	The count the machine quote was priced from.
`data[].dataset_version`	string	no	The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.
`data[].field_set`	string	no
`data[].delivery`	array of enum: `api`, `csv`, `google_sheets`	no
`data[].records`	integer (0 or more)	yes
`data[].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).
`data[].credits_remaining`	number (0 or more)	yes	The balance right after this order was charged.
`data[].cost_gbp`	number (0 or more)	yes	The charge in GBP excluding VAT at your plan's rate.
`data[].licence_expires_at`	string (date) or null	yes	When the licence ends; null for outright ownership.
`data[].licence`	`Licence`	yes	Licence terms as data, on every quote, order, records page and receipt. Records stay usable, pushable and re-downloadable free until reuse_until.
`data[].confirmed_by`	`ConfirmedBy`	yes	Who approved the spend and from which client, recorded in the audit trail and on invoices.
`data[].verification`	object	no	The real-time check at delivery, such as 4,102 checked, 4,071 passed.
`data[].records_url`	string (uri-reference)	yes	A path on https://mydatahub.emailmovers.com starting /v1/. Resolve it against the origin (RFC 3986), not by appending it to the server URL.
`data[].download_url`	string (uri-reference)	no	302 to a single-use signed URL that lives 5 minutes.
`data[].receipt_url`	string (uri-reference)	no	A path on https://mydatahub.emailmovers.com starting /v1/. Resolve it against the origin (RFC 3986), not by appending it to the server URL.
`data[].validation_report`	`ValidationReportLinks`	no	Present once the order is ready.
`data[].buyer_kit`	`BuyerKit`	no	Four signed documents that help the buyer use the list lawfully.
`data[].created_at`	string (date-time)	no
`data[].ready_at`	string (date-time) or null	no
`data[].failure`	string or null	no
`has_more`	boolean	yes	Whether another page follows.
`next_cursor`	string or null	yes	Pass as cursor to fetch the next page; null on the last page.

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.