GM_xmlhttpRequest

Description

This API method provides access to the chrome-privileged XMLHttpRequest object. This means that it is possible to issue requests to domains other than that of the current page.

Additional reference may be found at:

• http://www.w3.org/TR/XMLHttpRequest

⬆ ⬇ | Examples | See Also | Notes

Syntax

GM_xmlhttpRequest( details )

Value: Function
Compatibility: Greasemonkey 0.2.5 - 3.12.0
Access: @grant
Returns:

• undefined with Greasemonkey 1.8.0-
• Methods Object with Greasemonkey 1.9.0+

details Object

Properties	Event Handler Callbacks	Methods
method	onloadstart	abort
url	onprogress
headers	onabort
responseType	onerror
overrideMimeType	onload
data	ontimeout
binary	onloadend
user	onreadystatechange
password
upload
synchronous
timeout
mozAnon
anonymous

• All properties and event handler callbacks are optional except method and url.

⬆ ⬇

Properties

---

method

Value: String
Usage: details.method = "GET";

⬆ ⬇ ⇧

url

Value: String
Usage: details.url = "http://www.example.com/";

• The URL may be relative but it is strongly recommended to make it an absolute URL to avoid incorrect domain requests depending on the complexity of a user script.

⬆ ⬇ ⇧

headers

Value: Object
Usage: details.headers = {"User-Agent":"Mozilla/5.0"};

• The headers property is an object which is typically used to override the default browser generated headers, also known as atoms. It should contain the atom-value pairs of the headers to send.2

⬆ ⬇ ⇧

responseType

Value: Object
Compatibility: Greasemonkey 2.0.0+
Usage: details.responseType = "document";

• See also w3.org's DOM XMLHttpRequest responseType.

⬆ ⬇ ⇧

overrideMimeType

Value: String
Compatibility: Greasemonkey 0.6.8+
Usage: details.overrideMimeType = "text/html; charset=ISO-8859-1";

• While each character set name may have multiple aliases defined, there may be a preferred name which can be found at IANA.

⬆ ⬇ ⇧

data

Value: String
Usage: details.data = null; /* some code */ if (details.data) { /* some code */ }

• Note that if the data field contains form-encoded data, you must also set the header 'Content-Type': 'application/x-www-form-urlencoded' in the headers field.
• 1

⬆ ⬇ ⇧

binary

Value: Boolean
Compatibility: Greasemonkey 0.8.3+
Usage: details.binary = true;

• Sends data as type binary in Firefox 3.0.x or above.

⬆ ⬇ ⇧

user

Value: String
Compatibility: Greasemonkey 0.9.0+
Usage: details.user = "johndoe";

⬆ ⬇ ⇧

password

Value: String
Compatibility: Greasemonkey 0.9.0+
Usage: details.password = "password";

⬆ ⬇ ⇧

upload

Value: Object
Compatibility: Greasemonkey 0.9.9+

⬆ ⬇ ⇧

synchronous

Value: Boolean
Default: false
Compatibility: Greasemonkey 0.9.9+
Usage: details.synchronous = true;

• Sets transfers to synchronous mode possibly freezing the browser during uploading and downloading.

⬆ ⬇ ⇧

timeout

Value: Number
Default: 0
Compatibility: Greasemonkey 1.0.0+
Usage: details.timeout = 60000;

• Set the the timeout delay in milliseconds. Zero means use platform defaults for timeout.

⬆ ⬇ ⇧

mozAnon

anonymous

Value: Boolean
Default: false
Compatibility: Greasemonkey 3.8.0+
Usage: details.mozAnon = true;

• EXPERIMENTAL: Set the the request to not send authentication headers and/or cookies.
• anonymous is an alias for some non-Mozilla based browsers with user script engine peers.

⬆ ⬇ ⇧

Event Handler Callbacks

---

onloadstart

Usage: details.onloadstart = function (response) { /* some code */ };
Compatibility: Greasemonkey 3.8.0+
Returns: response Object

⬆ ⬇ ⇧

onprogress

Usage: details.onprogress = function (response) { /* some code */ };
Compatibility: Greasemonkey 0.9.9+
Returns: undefined, response Object

⬆ ⬇ ⇧

onabort

Usage: details.onabort = function (response) { /* some code */ };
Compatibility: Greasemonkey 0.9.9+
Returns: undefined, response Object

⬆ ⬇ ⇧

onerror

Usage: details.onerror = function (response) { /* some code */ };
Returns: undefined, response Object

⬆ ⬇ ⇧

onload

Usage: details.onload = function (response) { /* some code */ };
Returns: undefined, response Object

⬆ ⬇ ⇧

ontimeout

Usage: details.ontimeout = function (response) { /* some code */ };
Compatibility: Greasemonkey 0.9.9+
Returns: undefined, response Object

⬆ ⬇ ⇧

onloadend

Usage: details.onloadend = function (response) { /* some code */ };
Compatibility: Greasemonkey 3.8.0+
Returns: response Object

⬆ ⬇ ⇧

onreadystatechange

Usage: details.onreadystatechange = function (response) { /* some code */ };
Returns: undefined, response Object

⬆ ⬇ ⇧

Methods

---

abort

Usage: var req = GM_xmlhttpRequest({ /* Some intialization */ }); req.abort();
Compatibility: Greasemonkey 0.9.9+

⬆ ⬇ ⇧

response Object

Properties
status
statusText
readyState
responseText
responseXML
responseHeaders
finalUrl

⬆ ⬇

Properties

---

status

Value: Number
Usage: if (response.status == 200) { /* some code */ }

⬆ ⬇ ⇧

statusText

Value: String
Usage: if (response.statusText == "OK") { /* some code */ }

⬆ ⬇ ⇧

readyState

Value: Number
Usage: if (response.readyState == 4) { /* some code */ }

⬆ ⬇ ⇧

responseText

Value: String
Usage: alert(response.responseText);

⬆ ⬇ ⇧

responseXML

Value: null, Document Object
Compatibility: Greasemonkey 2.0.0+
Usage: alert(response.responseXML);

• Returns the Document Object of an xml document usually with media type of application/xml or text/xml for querying.
• NOTE: There may be no responseXML property, contrary to what people used to XMLHttpRequest might expect with, depending on the version of Greasemonkey and the browser. This is due to constantly changing security restrictions imposed on the XMLDocument created in the privileged GM core context. If it is absent one can easily create its own document object out of responseText using a DOMParser.

⬆ ⬇ ⇧

responseHeaders

Value: String
Usage: if (response.responseHeaders) { /* some code */ }

• The responseHeaders is the string representation of response headers returned by XMLHTTPRequest.getAllResponseHeaders().

⬆ ⬇ ⇧

finalUrl

Value: String
Compatibility: Greasemonkey 0.8.0+
Usage: if (response.finalUrl) { /* some code */ }

⬆ ⬇ ⇧

Examples

⬆ ⬇ | GET request | POST request | HEAD request

Core

GET request

GM_xmlhttpRequest({
  method: "GET",
  url: "http://www.example.net/",
  headers: {
    "User-Agent": "Mozilla/5.0", // If not specified, navigator.userAgent will be used.
    "Accept": "text/html" // If not specified, browser defaults will be used.
  },
  responseType: "document",
  onload: function (response) {
    // Attempt to create responseXML, if absent, in supported browsers
    var responseXML = response.responseXML;
    if (!responseXML) {
      try {
        responseXML = new DOMParser().parseFromString(response.responseText, "text/html");
      }
      catch (err) {}
    }

    GM_log([
      response.status,
      response.statusText,
      response.readyState,
      response.responseHeaders,
      response.responseText,
      response.finalUrl,
      responseXML
    ].join("\n"));
  }
});

⬆ ⬇ ⇧

POST request

When making a POST request, some sites require the Content-Type header to be included as such:

GM_xmlhttpRequest({
  method: "POST",
  url: "http://www.example.net/login",
  data: "username=johndoe&password=xyz123",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  onload: function (response) {
    if (response.responseText.indexOf("Logged in as") > -1)
      location.href = "http://www.example.net/dashboard";
  }
});

⬆ ⬇ ⇧

HEAD request

Sometimes responseText may be unnecessary, in which case a "HEAD" request is more advisable.

GM_xmlhttpRequest({
  url: "http://www.example.com",
  method: "HEAD",
  onload: function (response) {
    GM_log(response.responseHeaders);
  }
});

⬆ ⬇ ⇧

Notes

1 Some users have reported problems with international character sets. See these Mailing list threads

• mozdev.org thread 1
• mozdev.org thread 2

Resolved: Greasemonkey exposed the overrideMimeType method to allow changing of the desired charset.

2 Some header atoms may not actually work through GM_xmlhttpRequest. The Referer atom is one that is known to be recognized but appears to be content filtered by the browser. This may be due to security restrictions to keep user scripts from doing unsafe things.

• greasemonkey-dev thread
• userscripts.org topic⁸⁰⁸⁰^⋔

⬆