Poll report results

Poll status of an async report run, and fetch result pages once the run is done.

Returns the current state and (when ready) the result rows for an async report run. The URL is constructed by Emailgistics — you don’t build it yourself. Every reports endpoint response includes the polling URL in _links.self; use that URL directly.

GET/api/v1/reports/results/{reportResultsId}

Auth: Bearer API key — requires reporting scope
Async: Returns the same envelope as the originating endpoint
Pagination: Yes — see Pagination

Authorization

The API key must include the reporting scope. The result is additionally scoped server-side to the token that originated the run: even within the same customer account, a different key calling this endpoint with someone else’s reportResultsId returns 404.

If the originating endpoint requires additional scopes (for example, messages:read for receivedMessageDetail), polling does not re-check them. The originating call already enforced them.

Path parameters

reportResultsIdstring

The result identifier returned in _links.self of the originating reports response. UUID format.

Query parameters

The query parameters are baked into the URL Emailgistics gives you in _links.self, _links.next, and _links.prev. You normally don’t construct these yourself; just follow the URL as-is.

max?integerdefault 50

Maximum result rows per page. Capped at 500.

starting_after?string

Cursor — return rows whose id is greater than this. Mutually exclusive with ending_before.

ending_before?string

Cursor — return rows whose id is less than this. Mutually exclusive with starting_after.

Response

The response is the standard async result envelope. Three states matter:

Running

{
  "_links": {
    "self":   { "href": "https://c1.emailgistics.com/api/v1/reports/results/64cbb039-...?max=50", "method": "GET" },
    "origin": { "href": "https://c1.emailgistics.com/api/v1/reports/mailboxUserPerformance", "method": "POST", "body": { "parameters": { /* original request */ } } }
  },
  "status":   "running",
  "progress": 35,
  "result":   { "total": null, "data": [], "timeZone": "America/New_York" }
}

Done

{
  "_links": {
    "self":   { "href": "https://c1.emailgistics.com/api/v1/reports/results/64cbb039-...?max=50",                        "method": "GET" },
    "next":   { "href": "https://c1.emailgistics.com/api/v1/reports/results/64cbb039-...?max=50&starting_after=10050",   "method": "GET" },
    "origin": { "href": "https://c1.emailgistics.com/api/v1/reports/mailboxUserPerformance", "method": "POST", "body": { "parameters": { /* original request */ } } }
  },
  "status":   "done",
  "progress": 100,
  "result": {
    "total": 412,
    "dataCutoffTimestamp": "2026-05-01T08:14:00.0",
    "timeZone": "America/New_York",
    "data": [ /* result rows — schema depends on the originating endpoint: [Mailbox Performance](/docs/api/reports/mailbox-performance), [Mailbox User Performance](/docs/api/reports/mailbox-user-performance), [Mailbox Domain Performance](/docs/api/reports/mailbox-domain-performance), [Received Message Detail](/docs/api/reports/received-message-detail) */ ]
  }
}

Error

{
  "_links": {
    "self":   { "href": "https://c1.emailgistics.com/api/v1/reports/results/64cbb039-...", "method": "GET" },
    "origin": { "href": "https://c1.emailgistics.com/api/v1/reports/mailboxUserPerformance", "method": "POST", "body": { "parameters": { /* original request */ } } }
  },
  "status":   "error",
  "error": {
    "code":    "report_failed",
    "message": "The report could not be completed. Try again with a smaller date range."
  }
}

Polling cadence

Use exponential backoff starting at 2 seconds, capped at 30 seconds. As a rule of thumb, give up after about 5 minutes — re-issue the originating request from _links.origin if you exhaust your patience or the result expires.

Result expiry

Result IDs expire 24 hours after creation. Calling this endpoint with an expired reportResultsId returns 404. Re-issue the original request from _links.origin to start a fresh run.

Request

curl 'https://c1.emailgistics.com/api/v1/reports/results/64cbb039-15be-4c88-b3f2-59a17e2880e4?max=50' \
  -H 'Authorization: Bearer YOUR_API_KEY'

More examples

Pagination — follow `_links.next`

Once a result is done, follow the next link from the previous page directly. The cursor is already set.

curl 'https://c1.emailgistics.com/api/v1/reports/results/64cbb039-...?max=50&starting_after=10050' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "_links": {
    "self":   { "href": "https://c1.emailgistics.com/api/v1/reports/results/64cbb039-...?max=50&starting_after=10050", "method": "GET" },
    "prev":   { "href": "https://c1.emailgistics.com/api/v1/reports/results/64cbb039-...?max=50&ending_before=10051",  "method": "GET" },
    "next":   { "href": "https://c1.emailgistics.com/api/v1/reports/results/64cbb039-...?max=50&starting_after=10100", "method": "GET" },
    "origin": { "href": "https://c1.emailgistics.com/api/v1/reports/mailboxUserPerformance", "method": "POST", "body": { "parameters": { /* original request */ } } }
  },
  "status":   "done",
  "progress": 100,
  "result": {
    "total": 412,
    "dataCutoffTimestamp": "2026-05-01T08:14:00.0",
    "timeZone": "America/New_York",
    "data": [ /* the next 50 rows */ ]
  }
}

Errors

Status	When
`401`	API key missing, malformed, or expired.
`403`	Key is missing the `reporting` scope.
`404`	`reportResultsId` is unknown, expired (older than 24 hours), or belongs to a different token within your account.
`429`	Rate limit exceeded — see Rate limits.
`5xx`	Transient server error.

Error bodies follow the standard shape — see Errors.

A failed report run is not an HTTP error. The polling response stays 200 OK with status: "error" inside the result envelope. Check the envelope’s status field, not just the HTTP status, before treating a polling response as successful.

Result envelope and async polling — the lifecycle this endpoint participates in.
Pagination — _links.next / _links.prev semantics.
The reports endpoints all return polling URLs that target this endpoint:

Poll report results

On this page