# 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.

Source: https://emailmovers.com/mydatahub/docs/reference/mcp/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. 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}`](https://emailmovers.com/mydatahub/docs/reference/rest/get-order.md); [`GET /v1/orders`](https://emailmovers.com/mydatahub/docs/reference/rest/list-orders.md) |

> **Not yet live.** MyDataHub v2 is built and tested locally and is not yet live. The v2 hosts open at launch, date to confirm. This is what `tools/list` returns from https://mydatahub.emailmovers.com/mcp once v2 launches.

## 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:

```json
{
  "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](https://emailmovers.com/mydatahub/docs/errors.md).