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

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
▲