Reference

List orders

GET /v1/orders. Recent orders with status, counts and links, newest first.

Generated from the contractsView as Markdown

GET /v1/orders

Recent orders with status, counts and links, newest first.

Property	Value
Endpoint	`GET https://mydatahub.emailmovers.com/v1/orders`
Operation id	`listOrders`
Cost	Free (0 credits)
Access	An API key or an OAuth 2.1 token with the scope `orders:read`.
MCP tool	`get_order`
Tag	Orders

Request

Parameters

Name	In	Type	Required	Description
`status`	query	enum: `queued`, `building`, `verifying`, `ready`, `failed`, `cancelled`	no	queued, building, verifying, ready; failed if processing failed; cancelled (only while queued).
`limit`	query	integer (1 to 100)	no	Items per page, 1 to 100. Default 25.
`cursor`	query	string	no	An opaque cursor from next_cursor. Pass it back unchanged.
`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/orders" \
  -H "Authorization: Bearer $MYDATAHUB_API_KEY"

Responses

200: A page of orders.

Headers: RateLimit, RateLimit-Policy.

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.

Example response

{
  "data": [
    {
      "id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E",
      "status": "ready",
      "credits_charged": 5000,
      "records": 5000,
      "confirmed_by": {
        "method": "agent_key",
        "key_id": "key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA",
        "client_id": "https://claude.ai/oauth/claude-code-client-metadata",
        "user_agent": "claude-code/2.1",
        "mtls_certificate_fingerprint": null,
        "web_bot_auth_signature_agent": null,
        "confirmed_at": "2026-09-26T10:16:00Z"
      },
      "records_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/records",
      "quote_id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3",
      "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ",
      "credits_remaining": 1200,
      "cost_gbp": 1495,
      "licence_expires_at": "2027-09-26",
      "licence": {
        "type": "multi_use_12m",
        "reuse_until": "2027-09-26",
        "resale_prohibited": true,
        "permitted_channels": ["email", "telephone", "post"],
        "warranty_url": "https://emailmovers.com/trust/warranty",
        "terms_version": "2026-09"
      },
      "name": "Leeds marketing Q4",
      "dataset_version": "2026-W39",
      "field_set": "standard",
      "delivery": ["api", "csv"],
      "verification": {
        "checked": 5000,
        "passed": 4962,
        "replaced": 38
      },
      "download_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/download",
      "receipt_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/receipt",
      "validation_report": {
        "pdf_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/validation-report.pdf",
        "json_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/validation-report.json"
      },
      "buyer_kit": {
        "draft_lia_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/lia",
        "first_email_wording_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/first-email",
        "article30_stub_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/article30",
        "due_diligence_file_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/due-diligence"
      },
      "created_at": "2026-09-26T10:16:00Z",
      "ready_at": "2026-09-26T10:16:04Z",
      "failure": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

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.