Search code examples
google-apigmail-api

Why does changing maxResults cause the total number of results to change in Google API / Gmail API?

Why does changing the maxResults parameter cause the resultSizeEstimate to drastically change when calling gmail.users.messages.list()?

The Google API docs lists resultSizeEstimate as: Estimated total number of results.

... which means this final result set should not change just by altering the number of items returned per page.

Example A: maxResults: 1 ... resultSizeEstimate: 8

{
  "config": {
    "url": "https://www.googleapis.com/gmail/v1/users/me/messages?q=before%3A2021%2F1%2F9&maxResults=1",
    "method": "GET",
    "headers": {
      "Accept-Encoding": "gzip",
      "User-Agent": "google-api-nodejs-client/0.7.2 (gzip)",
      "Authorization": "Bearer [snip]",
      "Accept": "application/json"
    },
    "params": {
      "q": "before:2021/1/9",
      "maxResults": 1
    },
    "responseType": "json"
  },
  "data": {
    "messages": [ ... ],
    "nextPageToken": "14911817971227869758",
    "resultSizeEstimate": 8
  },
  "headers": {
    "alt-svc": "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"",
    "cache-control": "private",
    "connection": "close",
    "content-encoding": "gzip",
    "content-type": "application/json; charset=UTF-8",
    "date": "Sun, 09 Jan 2022 12:59:48 GMT",
    "server": "ESF",
    "transfer-encoding": "chunked",
    "vary": "Origin, X-Origin, Referer",
    "x-content-type-options": "nosniff",
    "x-frame-options": "SAMEORIGIN",
    "x-xss-protection": "0"
  },
  "status": 200,
  "statusText": "OK"
}

Example B: maxResults: 2 ... resultSizeEstimate: 12

{
  "config": {
    "url": "https://www.googleapis.com/gmail/v1/users/me/messages?q=before%3A2021%2F1%2F9&maxResults=2",
    "method": "GET",
    "headers": {
      "Accept-Encoding": "gzip",
      "User-Agent": "google-api-nodejs-client/0.7.2 (gzip)",
      "Authorization": "Bearer [snip]",
      "Accept": "application/json"
    },
    "params": {
      "q": "before:2021/1/9",
      "maxResults": 2
    },
    "responseType": "json"
  },
  "data": {
    "messages": [ ... ],
    "nextPageToken": "16903415066875011466",
    "resultSizeEstimate": 12
  },
  "headers": {
    "alt-svc": "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"",
    "cache-control": "private",
    "connection": "close",
    "content-encoding": "gzip",
    "content-type": "application/json; charset=UTF-8",
    "date": "Sun, 09 Jan 2022 13:10:48 GMT",
    "server": "ESF",
    "transfer-encoding": "chunked",
    "vary": "Origin, X-Origin, Referer",
    "x-content-type-options": "nosniff",
    "x-frame-options": "SAMEORIGIN",
    "x-xss-protection": "0"
  },
  "status": 200,
  "statusText": "OK"
}

Example C: maxResults: (not set) ... resultSizeEstimate: 412

{
  "config": {
    "url": "https://www.googleapis.com/gmail/v1/users/me/messages?q=before%3A2021%2F1%2F9",
    "method": "GET",
    "headers": {
      "Accept-Encoding": "gzip",
      "User-Agent": "google-api-nodejs-client/0.7.2 (gzip)",
      "Authorization": "Bearer [snip]",
      "Accept": "application/json"
    },
    "params": {
      "q": "before:2021/1/9"
    },
    "responseType": "json"
  },
  "data": {
    "messages": [ ... ],
    "nextPageToken": "16942818266524948378",
    "resultSizeEstimate": 412
  },
  "headers": {
    "alt-svc": "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"",
    "cache-control": "private",
    "connection": "close",
    "content-encoding": "gzip",
    "content-type": "application/json; charset=UTF-8",
    "date": "Sun, 09 Jan 2022 13:09:05 GMT",
    "server": "ESF",
    "transfer-encoding": "chunked",
    "vary": "Origin, X-Origin, Referer",
    "x-content-type-options": "nosniff",
    "x-frame-options": "SAMEORIGIN",
    "x-xss-protection": "0"
  },
  "status": 200,
  "statusText": "OK"
}
Solution

  • This was previously reported in Issue Tracker and was considered to be intended behavior by Google, since resultSizeEstimate is not expected to be exact; it's an "estimate":

    the reason why resultSizeEstimate shows differents values is due to its estimation. As mentioned in the documentation resultSizeEstimate is just an estimated total number of results but not the exact number of results.

    Reference: