Tampermonkey® by Jan Biniok

Table of Contents

GM_xmlhttpRequest(details)

The GM_xmlhttpRequest allows a userscripts to send an HTTP request and handle the response. The function takes a single parameter: an object containing the details of the request to be sent and the callback functions to be called when the response is received.

The object can have the following properties:

  • method - string, usually one of GET, HEAD, POST, PUT, DELETE, ...
  • url - string|URL|File|Blob, the destination URL or a Blob or File objectv5.4.6226+
  • headers e.g. user-agent, referer, ... (some special headers are not supported by Safari and Android browsers)
  • data - string|Blob|File|Object|Array|FormData|URLSearchParams?, some data to send via a POST request
  • redirect one of follow, error or manual; controls what to happen when a redirect is detected (build 6180+, enforces fetch mode)
  • cookie a cookie to be patched into the sent cookie set
  • cookiePartition v5.2+ object?, containing the partition key to be used for sent and received partitioned cookies
    • topLevelSite string?, representing the top frame site for partitioned cookies
  • binary send the data string in binary mode
  • nocache don't cache the resource
  • revalidate revalidate maybe cached content
  • timeout a timeout in ms
  • context a property which will be added to the response object
  • responseType one of arraybuffer, blob, json or stream
  • overrideMimeType a MIME type for the request
  • anonymous don't send cookies with the request (enforces fetch mode)
  • fetch use a fetch instead of a XMLHttpRequest request (at Chrome this causes details.timeout and xhr.onprogress to not work and makes xhr.onreadystatechange receive only readyState DONE (==4) events)
  • proxy v5.5.6233+ | Firefox only Explicit proxy configuration
    • type string, 'direct' | 'http' | 'https' | 'socks' | 'socks4', the kind of proxy to use
    • host string, hostname of the proxy server
    • port number, port number of the proxy server
    • username string?, username for SOCKS proxies
    • password string?, password for SOCKS proxies
    • proxyDNS boolean?, use the proxy for DNS resolution (only for “socks”/“socks4”)
    • failoverTimeout number?, fail‑over timeout in seconds
    • proxyAuthorizationHeader string?, value sent as Proxy-Authorization for HTTP/HTTPS proxies
    • connectionIsolationKey string?, additional key for connection isolation
  • user string?, a user name for authentication
  • password string?, a password
  • onabort callback to be executed if the request was aborted
  • onerror callback to be executed if the request ended up with an error
  • onloadstart callback to be executed on load start, provides access to the stream object if responseType is set to stream
  • onprogress callback to be executed if the request made some progress
  • onreadystatechange callback to be executed if the request's readyState changed
  • ontimeout callback to be executed if the request failed due to a timeout
  • onload callback to be executed if the request was loaded.
      function(response) {
    // response is an object containing the details of the response
  }
    response has the following attributes:
    • finalUrl - the final URL after all redirects from where the data was loaded
    • readyState - the request's readyState
    • status - the request's status
    • statusText - the request's status text
    • responseHeaders - the request's response headers
    • response - the response data as object if details.responseType was set
    • responseXML - the response data as XML document
    • responseText - the response data as plain string

Networking

GM_xmlhttpRequest is dispatched by Tampermonkey's background context.

Proxy. Tampermonkey does not implement its own proxy resolution (PAC, WPAD, WinHTTP, or NO_PROXY). Requests use the browser's native networking stack, so proxy settings follow whatever the browser is configured to use. The proxy property on the request details allows you to override this and route a specific request through an explicit proxy server.

Certificates. No custom certificate or trust-store handling is performed. Requests use the browser's TLS stack, so they trust whichever root certificates the browser trusts (e.g., OS trust store on Chrome, Firefox's own certificate database on Firefox).

Authentication Challenges (401/407). HTTP 401 and 407 responses come from the destination server or proxy before Tampermonkey can intercept them. They must be resolved at the browser or OS proxy-authentication level, or by providing credentials via the user/password properties.

GM_xmlhttpRequest returns an object with the following property:

  • abort - function to be called to cancel this request

GM.xmlHttpRequest returns a promise that resolves to the response and also has an abort function.

Here is an example of how the GM_xmlhttpRequest function might be used in a userscript:

GM_xmlhttpRequest({
  method: "GET",
  url: "https://example.com/",
  headers: {
    "Content-Type": "application/json"
  },
  onload: function(response) {
    console.log(response.responseText);
  }
});

const r = await GM.xmlHttpRequest({ url: "https://example.com/" }).catch(e => console.error(e));
console.log(r.responseText);

Note: the synchronous flag at details is not supported

Important::

  • If you want to use this method then please also check the documentation about @connect
  • The promise-based version of this function is called GM.xmlHttpRequest (with a uppercase "h" in "http")
Imprint Privacy Policy
▲