jQuery.

ajax() | jQuery API Documentation

1 of 17

http://api.jquery.com/jquery.ajax/

Plugins (http://plugins.jquery.com/)

Contribute (http://contribute.jquery.org/)

Support (https://jquery.org/support/)

jQuery Foundation (https://jquery.org/)

Events (http://events.jquery.org/)

Ajax (//api.jquery.com
/category/ajax/)
Global Ajax Event
Handlers
(//api.jquery.com
/category
/ajax/globalajax-eventhandlers/)
Helper Functions
(//api.jquery.com
/category
/ajax/helperfunctions/)
Low-Level
Interface
(//api.jquery.com
/category/ajax/lowlevel-interface/)
Shorthand
Methods
(//api.jquery.com
/category
/ajax/shorthandmethods/)

Attributes
(//api.jquery.com

Categories: Ajax (//api.jquery.com/category/ajax/) > Low-Level Interface (//api.jquery.com

/category/ajax/low-level-interface/)

Description: Perform an asynchronous HTTP (Ajax) request.

url
Type: String (http://api.jquery.com/Types/#String)
A string containing the URL to which the request is sent.
settings
Type: PlainObject (http://api.jquery.com/Types/#PlainObject)
A set of key/value pairs that configure the Ajax request. All settings
are optional. A default can be set for any option with $.ajaxSetup()
(/jQuery.ajaxSetup/). See jQuery.ajax( settings ) below for a
complete list of all settings.

settings
Type: PlainObject (http://api.jquery.com/Types/#PlainObject)
A set of key/value pairs that configure the Ajax request. All settings
are optional. A default can be set for any option with $.ajaxSetup()
(/jQuery.ajaxSetup/).

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

2 of 17

/category/attributes/)
Callbacks Object
(//api.jquery.com
/category/callbacksobject/)
Core (//api.jquery.com
/category/core/)
CSS (//api.jquery.com
/category/css/)
Data (//api.jquery.com
/category/data/)
Deferred Object
(//api.jquery.com
/category/deferredobject/)
Deprecated
(//api.jquery.com
/category
/deprecated/)
Deprecated 1.3
(//api.jquery.com
/category
/deprecated
/deprecated-1.3/)
Deprecated 1.7
(//api.jquery.com
/category
/deprecated
/deprecated-1.7/)
Deprecated 1.8
(//api.jquery.com
/category
/deprecated
/deprecated-1.8/)
Deprecated 1.10
(//api.jquery.com
/category
/deprecated
/deprecated-1.10/)

Dimensions
(//api.jquery.com
/category
/dimensions/)

http://api.jquery.com/jquery.ajax/

accepts (default:
)
Type: PlainObject (http://api.jquery.com/Types/#PlainObject)
The content type sent in the request header that tells the
server what kind of response it will accept in return.
async (default:
)
Type: Boolean (http://api.jquery.com/Types/#Boolean)
By default, all requests are sent asynchronously (i.e. this is
set to
by default). If you need synchronous requests,
set this option to
. Cross-domain requests and
requests do not support synchronous
operation. Note that synchronous requests may temporarily
lock the browser, disabling any actions while the request is
active. As of jQuery 1.8, the use of
with
jqXHR (
) is deprecated; you must use the
success/error/complete callback options instead of the
corresponding methods of the jqXHR object such as
or the deprecated
.
beforeSend
Type: Function (http://api.jquery.com/Types/#Function)(
jqXHR (http://api.jquery.com/Types/#jqXHR) jqXHR,
PlainObject (http://api.jquery.com/Types/#PlainObject)
settings )
A pre-request callback function that can be used to modify
the jqXHR (in jQuery 1.4.x, XMLHTTPRequest) object before
it is sent. Use this to set custom headers, etc. The jqXHR
and settings objects are passed as arguments. This is an
Ajax Event (/Ajax_Events/). Returning
in the
function will cancel the request. As of jQuery
1.5, the
option will be called regardless of the
type of request.
cache (default:
)
Type: Boolean (http://api.jquery.com/Types/#Boolean)
If set to
, it will force requested pages not to be
cached by the browser. Note: Setting
to false will only
work correctly with HEAD and GET requests. It works by
appending "_={timestamp}" to the GET parameters. The
parameter is not needed for other types of requests, except
in IE8 when a POST is made to a URL that has already been
requested by a GET.
complete
Type: Function (http://api.jquery.com/Types/#Function)(
jqXHR (http://api.jquery.com/Types/#jqXHR) jqXHR, String
(http://api.jquery.com/Types/#String) textStatus )
A function to be called when the request finishes (after
and
callbacks are executed). The function
gets passed two arguments: The jqXHR (in jQuery 1.4.x,
XMLHTTPRequest) object and a string categorizing the
status of the request (
,
,
,
,
, or
). As of
jQuery 1.5, the
setting can accept an array of

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

3 of 17

Effects
(//api.jquery.com
/category/effects/)
Basics
(//api.jquery.com
/category/effects
/basics/)
Custom
(//api.jquery.com
/category/effects
/custom-effects/)
Fading
(//api.jquery.com
/category/effects
/fading/)
Sliding
(//api.jquery.com
/category/effects
/sliding/)

Events
(//api.jquery.com
/category/events/)
Browser Events
(//api.jquery.com
/category/events
/browser-events/)

http://api.jquery.com/jquery.ajax/

functions. Each function will be called in turn. This is an Ajax

Event (/Ajax_Events/).
contents
Type: PlainObject (http://api.jquery.com/Types/#PlainObject)
An object of string/regular-expression pairs that determine
how jQuery will parse the response, given its content type.
(version added: 1.5 (/category/version/1.5/))
contentType (default:
)
Type: String (http://api.jquery.com/Types/#String)
When sending data to the server, use this content type.
Default is "application/x-www-form-urlencoded;
charset=UTF-8", which is fine for most cases. If you explicitly
pass in a content-type to
, then it is always sent to
the server (even if no data is sent). The W3C
XMLHttpRequest specification dictates that the charset is
always UTF-8; specifying another charset will not force the
browser to change the encoding. Note: For cross-domain
requests, setting the content type to anything other than
,
, or
will trigger the
browser to send a preflight OPTIONS request to the server.
context
Type: PlainObject (http://api.jquery.com/Types/#PlainObject)
This object will be made the context of all Ajax-related
callbacks. By default, the context is an object that represents
the ajax settings used in the call (
merged
with the settings passed to
). For example, specifying
a DOM element as the context will make that the context for
the
callback of a request, like so:

Document Loading
(//api.jquery.com
/category/events
/documentloading/)
Event Handler
Attachment
(//api.jquery.com
/category/events
/event-handlerattachment/)
Event Object
(//api.jquery.com
/category/events
/event-object/)

converters (default:
)
Type: PlainObject (http://api.jquery.com/Types/#PlainObject)
An object containing dataType-to-dataType converters. Each
converter's value is a function that returns the transformed
value of the response. (version added: 1.5 (/category
/version/1.5/))
crossDomain (default:

Form Events
(//api.jquery.com
/category/events

)
Type: Boolean (http://api.jquery.com/Types/#Boolean)
If you wish to force a crossDomain request (such as JSONP)

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

4 of 17

/form-events/)
Keyboard Events
(//api.jquery.com
/category/events
/keyboard-events/)
Mouse Events
(//api.jquery.com
/category/events
/mouse-events/)

Forms
(//api.jquery.com

http://api.jquery.com/jquery.ajax/

on the same domain, set the value of crossDomain to

.
This allows, for example, server-side redirection to another
domain. (version added: 1.5 (/category/version/1.5/))
data
Type: PlainObject (http://api.jquery.com/Types/#PlainObject)
or String (http://api.jquery.com/Types/#String) or Array
(http://api.jquery.com/Types/#Array)
Data to be sent to the server. It is converted to a query string,
if not already a string. It's appended to the url for
GET-requests. See
option to prevent this
automatic processing. Object must be Key/Value pairs. If
value is an Array, jQuery serializes multiple values with same
key based on the value of the
setting
(described below).

/category/forms/)
Internals
(//api.jquery.com
/category/internals/)
Manipulation
(//api.jquery.com
/category
/manipulation/)
Class Attribute
(//api.jquery.com
/category
/manipulation
/class-attribute/)
Copying
(//api.jquery.com
/category
/manipulation
/copying/)

dataFilter
Type: Function (http://api.jquery.com/Types/#Function)(
String (http://api.jquery.com/Types/#String) data, String
(http://api.jquery.com/Types/#String) type ) => Object
(http://api.jquery.com/Types/#Object)
A function to be used to handle the raw response data of
XMLHttpRequest.This is a pre-filtering function to sanitize the
response. You should return the sanitized data. The function
accepts two arguments: The raw data returned from the
server and the 'dataType' parameter.
dataType (default:
)
Type: String (http://api.jquery.com/Types/#String)
The type of data that you're expecting back from the server.
If none is specified, jQuery will try to infer it based on the
MIME type of the response (an XML MIME type will yield
XML, in 1.4 JSON will yield a JavaScript object, in 1.4 script
will execute the script, and anything else will be returned as a
string). The available types (and the result passed as the first
argument to your success callback) are:

DOM Insertion,
Around
(//api.jquery.com

"xml": Returns a XML document that can be processed

via jQuery.

/category
/manipulation
/dom-insertionaround/)

"html": Returns HTML as plain text; included script tags

are evaluated when inserted in the DOM.

DOM Insertion,
Inside
(//api.jquery.com
/category
/manipulation
/dom-insertioninside/)
DOM Insertion,

"script": Evaluates the response as JavaScript and

returns it as plain text. Disables caching by appending
a query string parameter, "_=[TIMESTAMP]", to the
URL unless the
option is set to
. Note:
This will turn POSTs into GETs for remote-domain
requests.
"json": Evaluates the response as JSON and returns a
JavaScript object. The JSON data is parsed in a strict
manner; any malformed JSON is rejected and a parse
error is thrown. As of jQuery 1.9, an empty response is

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

5 of 17

Outside
(//api.jquery.com
/category
/manipulation
/dom-insertionoutside/)
DOM Removal
(//api.jquery.com
/category
/manipulation
/dom-removal/)
DOM
Replacement
(//api.jquery.com
/category
/manipulation
/dom-replacement/)
General Attributes
(//api.jquery.com
/category
/manipulation
/generalattributes/)
Style Properties
(//api.jquery.com
/category
/manipulation
/style-properties/)

Miscellaneous
(//api.jquery.com
/category
/miscellaneous/)
Collection
Manipulation
(//api.jquery.com
/category
/miscellaneous
/collectionmanipulation/)
Data Storage
(//api.jquery.com
/category
/miscellaneous
/data-storage/)
DOM Element

http://api.jquery.com/jquery.ajax/

also rejected; the server should return a response of

or
instead. (See json.org (http://json.org/) for
more information on proper JSON formatting.)
"jsonp": Loads in a JSON block using JSONP
(http://bob.pythonmac.org/archives/2005/12/05/remotejson-jsonp/). Adds an extra "?callback=?" to the end of
your URL to specify the callback. Disables caching by
appending a query string parameter,
"_=[TIMESTAMP]", to the URL unless the
option is set to
.
"text": A plain text string.
multiple, space-separated values: As of jQuery 1.5,
jQuery can convert a dataType from what it received in
the Content-Type header to what you require. For
example, if you want a text response to be treated as
XML, use "text xml" for the dataType. You can also
make a JSONP request, have it received as text, and
interpreted by jQuery as XML: "jsonp text xml."
Similarly, a shorthand string such as "jsonp xml" will
first attempt to convert from jsonp to xml, and, failing
that, convert from jsonp to text, and then from text to
xml.
error
Type: Function (http://api.jquery.com/Types/#Function)(
jqXHR (http://api.jquery.com/Types/#jqXHR) jqXHR, String
(http://api.jquery.com/Types/#String) textStatus, String
(http://api.jquery.com/Types/#String) errorThrown )
A function to be called if the request fails. The function
receives three arguments: The jqXHR (in jQuery 1.4.x,
XMLHttpRequest) object, a string describing the type of error
that occurred and an optional exception object, if one
occurred. Possible values for the second argument (besides
) are
,
,
, and
. When an HTTP error occurs,
receives the textual portion of the HTTP status, such as "Not
Found" or "Internal Server Error." As of jQuery 1.5, the
setting can accept an array of functions. Each
function will be called in turn. Note: This handler is not called
for cross-domain script and cross-domain JSONP requests.
This is an Ajax Event (/Ajax_Events/).
global (default:
)
Type: Boolean (http://api.jquery.com/Types/#Boolean)
Whether to trigger global Ajax event handlers for this
request. The default is
. Set to
to prevent the
global handlers like
or
from being
triggered. This can be used to control various Ajax Events
(/Ajax_Events/).
headers (default:
)
Type: PlainObject (http://api.jquery.com/Types/#PlainObject)

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

6 of 17

Methods
(//api.jquery.com
/category
/miscellaneous
/dom-elementmethods/)
Setup Methods
(//api.jquery.com
/category
/miscellaneous
/setup-methods/)

Offset
(//api.jquery.com
/category/offset/)
Properties
(//api.jquery.com
/category/properties/)
Properties of
jQuery Object
Instances
(//api.jquery.com
/category
/properties/jqueryobject-instanceproperties/)
Properties of the
Global jQuery
Object
(//api.jquery.com
/category
/properties/globaljquery-objectproperties/)

Removed
(//api.jquery.com
/category/removed/)
Selectors
(//api.jquery.com
/category/selectors/)
Attribute
(//api.jquery.com
/category/selectors
/attributeselectors/)

http://api.jquery.com/jquery.ajax/

An object of additional header key/value pairs to send along

with requests using the XMLHttpRequest transport. The
header
is always
added, but its default
value can be
changed here. Values in the
setting can also be
overwritten from within the
function. (version
added: 1.5 (/category/version/1.5/))
ifModified (default:
)
Type: Boolean (http://api.jquery.com/Types/#Boolean)
Allow the request to be successful only if the response has
changed since the last request. This is done by checking the
Last-Modified header. Default value is
, ignoring the
header. In jQuery 1.4 this technique also checks the 'etag'
specified by the server to catch unmodified data.
isLocal (default:
)
Type: Boolean (http://api.jquery.com/Types/#Boolean)
Allow the current environment to be recognized as "local,"
(e.g. the filesystem), even if jQuery does not recognize it as
such by default. The following protocols are currently
recognized as local:
,
, and
. If the
setting needs modification, it is recommended to do
so once in the
method. (version added:
1.5.1 (/category/version/1.5.1/))
jsonp
Type: String (http://api.jquery.com/Types/#String)
Override the callback function name in a JSONP request.
This value will be used instead of 'callback' in the 'callback=?'
part of the query string in the url. So
would result in
passed to the server. As of jQuery 1.5, setting the
option to
prevents jQuery from adding the "?callback"
string to the URL or attempting to use "=?" for
transformation. In this case, you should also explicitly set the
setting. For example,

jsonpCallback
Type: String (http://api.jquery.com/Types/#String) or Function
(http://api.jquery.com/Types/#Function)()
Specify the callback function name for a JSONP request.
This value will be used instead of the random name
automatically generated by jQuery. It is preferable to let
jQuery generate a unique name as it'll make it easier to
manage the requests and provide callbacks and error
handling. You may want to specify the callback when you
want to enable better browser caching of GET requests. As
of jQuery 1.5, you can also use a function for this setting, in
which case the value of
is set to the return
value of that function.
mimeType
Type: String (http://api.jquery.com/Types/#String)

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

7 of 17

Basic
(//api.jquery.com
/category/selectors
/basiccss-selectors/)
Basic Filter
(//api.jquery.com
/category/selectors
/basic-filterselectors/)
Child Filter
(//api.jquery.com
/category/selectors
/child-filterselectors/)
Content Filter
(//api.jquery.com
/category/selectors
/content-filterselector/)
Form
(//api.jquery.com
/category/selectors
/form-selectors/)
Hierarchy
(//api.jquery.com
/category/selectors
/hierarchyselectors/)
jQuery Extensions
(//api.jquery.com
/category/selectors
/jquery-selectorextensions/)
Visibility Filter
(//api.jquery.com
/category/selectors
/visibility-filterselectors/)

Traversing
(//api.jquery.com
/category/traversing/)
Filtering
(//api.jquery.com

http://api.jquery.com/jquery.ajax/

A mime type to override the XHR (XMLHttpRequest) mime

type. (version added: 1.5.1 (/category/version/1.5.1/))
password
Type: String (http://api.jquery.com/Types/#String)
A password to be used with XMLHttpRequest in response to
an HTTP access authentication request.
processData (default:
)
Type: Boolean (http://api.jquery.com/Types/#Boolean)
By default, data passed in to the data option as an object
(technically, anything other than a string) will be processed
and transformed into a query string, fitting to the default
content-type "application/x-www-form-urlencoded". If you
want to send a DOMDocument, or other non-processed data,
set this option to
.
scriptCharset
Type: String (http://api.jquery.com/Types/#String)
Only applies when the "script" transport is used (e.g., crossdomain requests with "jsonp" or "script" dataType and "GET"
type). Sets the
attribute on the script tag used in
the request. Used when the character set on the local page
is not the same as the one on the remote script.
statusCode (default:
)
Type: PlainObject (http://api.jquery.com/Types/#PlainObject)
An object of numeric HTTP codes and functions to be called
when the response has the corresponding code. For
example, the following will alert when the response status is
a 404:

If the request is successful, the status code functions take

the same parameters as the success callback; if it results in
an error (including 3xx redirect), they take the same
parameters as the
callback.
(version added: 1.5 (/category/version/1.5/))
success
Type: Function (http://api.jquery.com/Types/#Function)(
PlainObject (http://api.jquery.com/Types/#PlainObject) data,
String (http://api.jquery.com/Types/#String) textStatus, jqXHR
(http://api.jquery.com/Types/#jqXHR) jqXHR )
A function to be called if the request succeeds. The function
gets passed three arguments: The data returned from the
server, formatted according to the
parameter; a
string describing the status; and the
(in jQuery 1.4.x,

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

8 of 17

http://api.jquery.com/jquery.ajax/

/category
/traversing
/filtering/)

XMLHttpRequest) object. As of jQuery 1.5, the success

setting can accept an array of functions. Each function will be
called in turn. This is an Ajax Event (/Ajax_Events/).

Miscellaneous
Traversing
(//api.jquery.com
/category
/traversing
/miscellaneoustraversal/)

timeout
Type: Number (http://api.jquery.com/Types/#Number)
Set a timeout (in milliseconds) for the request. This will
override any global timeout set with $.ajaxSetup()
(/jQuery.ajaxSetup/). The timeout period starts at the point
the
call is made; if several other requests are in
progress and the browser has no connections available, it is
possible for a request to time out before it can be sent. In
jQuery 1.4.x and below, the XMLHttpRequest object will be
in an invalid state if the request times out; accessing any
object members may throw an exception. In Firefox 3.0+
only, script and JSONP requests cannot be cancelled by a
timeout; the script will run even if it arrives after the timeout
period.

Tree Traversal
(//api.jquery.com
/category
/traversing/treetraversal/)

Utilities
(//api.jquery.com
/category/utilities/)
Version
(//api.jquery.com
/category/version/)
Version 1.0
(//api.jquery.com
/category/version
/1.0/)
Version 1.0.4
(//api.jquery.com
/category/version
/1.0.4/)
Version 1.1
(//api.jquery.com
/category/version
/1.1/)
Version 1.1.2
(//api.jquery.com
/category/version
/1.1.2/)
Version 1.1.3
(//api.jquery.com
/category/version
/1.1.3/)
Version 1.1.4
(//api.jquery.com
/category/version

traditional
Type: Boolean (http://api.jquery.com/Types/#Boolean)
Set this to
if you wish to use the traditional style of
param serialization (/jQuery.param/).
type (default:
)
Type: String (http://api.jquery.com/Types/#String)
The type of request to make ("POST" or "GET"), default is
"GET". Note: Other HTTP request methods, such as PUT
and DELETE, can also be used here, but they are not
supported by all browsers.
url (default:
)
Type: String (http://api.jquery.com/Types/#String)
A string containing the URL to which the request is sent.
username
Type: String (http://api.jquery.com/Types/#String)
A username to be used with XMLHttpRequest in response to
an HTTP access authentication request.
xhr (default:
)
Type: Function (http://api.jquery.com/Types/#Function)()
Callback for creating the XMLHttpRequest object. Defaults to
the ActiveXObject when available (IE), the XMLHttpRequest
otherwise. Override to provide your own implementation for
XMLHttpRequest or enhancements to the factory.
xhrFields
Type: PlainObject (http://api.jquery.com/Types/#PlainObject)
An object of fieldName-fieldValue pairs to set on the native
object. For example, you can use it
to set
to
for cross-domain requests
if needed.

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

9 of 17

http://api.jquery.com/jquery.ajax/

/1.1.4/)
Version 1.2
(//api.jquery.com
/category/version
/1.2/)
Version 1.2.3
(//api.jquery.com
/category/version
/1.2.3/)
Version 1.2.6
(//api.jquery.com
/category/version
/1.2.6/)
Version 1.3
(//api.jquery.com
/category/version
/1.3/)
Version 1.4
(//api.jquery.com
/category/version
/1.4/)
Version 1.4.1
(//api.jquery.com
/category/version
/1.4.1/)
Version 1.4.2
(//api.jquery.com
/category/version
/1.4.2/)
Version 1.4.3
(//api.jquery.com
/category/version
/1.4.3/)
Version 1.4.4
(//api.jquery.com
/category/version
/1.4.4/)
Version 1.5
(//api.jquery.com
/category/version
/1.5/)

In jQuery 1.5, the

property was not
propagated to the native
and thus CORS requests
requiring it would ignore this flag. For this reason, we
recommend using jQuery 1.5.1+ should you require the use
of it.
(version added: 1.5.1 (/category/version/1.5.1/))

The
function underlies all Ajax requests sent by jQuery. It is
often unnecessary to directly call this function, as several higher-level
alternatives like
and
are
available and are easier to use. If less common options are required,
though,
can be used more flexibly.
At its simplest, the

function can be called with no arguments:

Note: Default settings can be set globally by using the

function.
This example, using no options, loads the contents of the current page,
but does nothing with the result. To use the result, you can implement
one of the callback functions.

The jQuery XMLHttpRequest (jqXHR) object returned by

as of
jQuery 1.5 is a superset of the browser's native XMLHttpRequest object.
For example, it contains
and
properties, as
well as a
method. When the transport mechanism
is something other than XMLHttpRequest (for example, a script tag for a
JSONP request) the
object simulates native XHR functionality
where possible.
As of jQuery 1.5.1, the
object also contains the
method (it was available in jQuery 1.4.x, as well,
but was temporarily removed in jQuery 1.5). The
method may be used in the
callback function, for
example, to modify the response content-type header:

Version 1.5.1
(//api.jquery.com
/category/version

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

10 of 17

http://api.jquery.com/jquery.ajax/

/1.5.1/)
Version 1.6
(//api.jquery.com
/category/version
/1.6/)
Version 1.7
(//api.jquery.com
/category/version
/1.7/)
Version 1.8
(//api.jquery.com
/category/version
/1.8/)
Version 1.9
(//api.jquery.com
/category/version
/1.9/)

The jqXHR objects returned by

as of jQuery 1.5 implement the
Promise interface, giving them all the properties, methods, and behavior
of a Promise (see Deferred object (/category/deferred-object/) for more
information). These methods take one or more function arguments that
are called when the
request terminates. This allows you to
assign multiple callbacks on a single request, and even to assign
callbacks after the request may have completed. (If the request is already
complete, the callback is fired immediately.) Available Promise methods
of the jqXHR object include:
jqXHR.done(function( data, textStatus, jqXHR ) {});
An alternative construct to the success callback option, the
method replaces the deprecated
method. Refer to
for
implementation details.
jqXHR.fail(function( jqXHR, textStatus, errorThrown ) {});
An alternative construct to the error callback option, the
method replaces the deprecated
method. Refer to
for implementation details.
jqXHR.always(function( data|jqXHR, textStatus,
jqXHR|errorThrown ) { });
An alternative construct to the complete callback option, the
method replaces the deprecated
method.
In response to a successful request, the function's arguments are
the same as those of
: data, textStatus, and the jqXHR
object. For failed requests the arguments are the same as those of
: the jqXHR object, textStatus, and errorThrown. Refer to
for implementation
details.
jqXHR.then(function( data, textStatus, jqXHR ) {}, function(
jqXHR, textStatus, errorThrown ) {});
Incorporates the functionality of the
and
methods, allowing (as of jQuery 1.8) the underlying Promise to be
manipulated. Refer to
(/deferred.then/) for
implementation details.

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

11 of 17

http://api.jquery.com/jquery.ajax/

Deprecation Notice: The

,
,
and
callbacks are deprecated as of jQuery
1.8. To prepare your code for their eventual removal, use
,
, and
instead.

The
reference within all callbacks is the object in the
option passed to
in the settings; if
is not specified,
is a reference to the Ajax settings themselves.
For backward compatibility with
expose the following properties and methods:

,a

object will

and/or
when the underlying request
responded with xml and/or text, respectively
which departs from the
standard by replacing the old value with the new one rather than
concatenating the new value to the old one

No

mechanism is provided, however, since

,

The

, and

cover all conceivable requirements.

and

options

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

12 of 17

http://api.jquery.com/jquery.ajax/

all accept callback functions that are invoked at the appropriate times.
As of jQuery 1.5, the
and
, and, as of jQuery 1.6,
callback hooks are first-in, first-out managed queues, allowing for more
than one callback for each hook. See Deferred object methods (/category
/deferred-object/), which are implemented internally for these
callback hooks.
The callback hooks provided by

are as follows:

callback option is invoked; it receives the

object and the
object as parameters.
the

callback option is invoked, if the request fails. It receives

, a string indicating the error type, and an exception

object if applicable. Some built-in errors will provide a string as

the exception object: "abort", "timeout", "No Transport".
callback option is invoked immediately upon
successful receipt of response data. It receives the returned
data and the value of
, and must return the (possibly
altered) data to pass on to
.
callback option is invoked, if the request succeeds. It
receives the returned data, a string containing the success
code, and the
object.
Promise callbacks
,
,
, and
are invoked, in the order they are registered.
callback option fires, when the request finishes,
whether in failure or success. It receives the
object, as
well as a string containing the success or error code.

Different types of response to

call are subjected to different
kinds of pre-processing before being passed to the success handler. The
type of pre-processing depends by default upon the Content-Type of the
response, but can be set explicitly using the
option. If the
option is provided, the Content-Type header of the response
will be disregarded.
The available data types are
.

, and

If
or
is specified, no pre-processing occurs. The data is
simply passed on to the success handler, and made available through the
property of the
object.
If
is specified, the response is parsed using
(/jQuery.parseXML/) before being passed, as an
(http://api.jquery.com/Types/#XMLDocument), to the success handler.
The XML document is made available through the
property
of the
object.

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

13 of 17

http://api.jquery.com/jquery.ajax/

If
is specified, the response is parsed using
(/jQuery.parseJSON/) before being passed, as an object, to the success
handler. The parsed JSON object is made available through the
property of the
object.
If
is specified,
will execute the JavaScript that is
received from the server before passing it on to the success handler as a
string.
If
is specified,
will automatically append a query string
parameter of (by default)
to the URL. The
and
properties of the settings passed to
can be
used to specify, respectively, the name of the query string parameter and
the name of the JSONP callback function. The server should return valid
JavaScript that passes the JSON response into the callback function.
will execute the returned JavaScript, calling the JSONP
callback function, before passing the JSON object contained in the
response to the
success handler.
For more information on JSONP, see the original post detailing its use
(http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/).

By default, Ajax requests are sent using the GET HTTP method. If the
POST method is required, the method can be specified by setting a value
for the
option. This option affects how the contents of the
option are sent to the server. POST data will always be transmitted to the
server using UTF-8 charset, per the W3C XMLHTTPRequest standard.
The

option can contain either a query string of the form

, or an object of the form
. If the latter form is used, the data is
converted into a query string using
before it is sent. This processing can be circumvented by setting
to
. The processing might be undesirable if you wish
to send an XML object to the server; in this case, change the
option from
more appropriate MIME type.

to a

The

option prevents handlers registered using

,
, and similar methods
from firing when this request would trigger them. This can be useful to,
for example, suppress a loading indicator that was implemented with
if the requests are frequent and brief. With
cross-domain script and JSONP requests, the global option is
automatically set to
. See the descriptions of these methods below
for more details. See the descriptions of these methods below for more
details.

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

14 of 17

http://api.jquery.com/jquery.ajax/

If the server performs HTTP authentication before providing a response,

the user name and password pair can be sent via the
and
options.
Ajax requests are time-limited, so errors can be caught and handled to
provide a better user experience. Request timeouts are usually either left
at their default or set as a global default using
rather than being overridden for specific
requests with the
option.
By default, requests are always issued, but the browser may serve
results out of its cache. To disallow use of the cached results, set
to
. To cause the request to report failure if the asset has not been
modified since the last request, set
to
.
The
allows the character set to be explicitly specified for
requests that use a
tag (that is, a type of
or
).
This is useful if the script and host page have differing character sets.
The first letter in Ajax stands for "asynchronous," meaning that the
operation occurs in parallel and the order of completion is not
guaranteed. The
option to
defaults to
, indicating
that code execution can continue after the request is made. Setting this
option to
(and thus making the call no longer asynchronous) is
strongly discouraged, as it can cause the browser to become
unresponsive.
The
function returns the
object that it
creates. Normally jQuery handles the creation of this object internally, but
a custom function for manufacturing one can be specified using the
option. The returned object can generally be discarded, but does provide
a lower-level interface for observing and manipulating the request. In
particular, calling
completes.

on the object will halt the request before it

As of jQuery 1.5, jQuery's Ajax implementation includes prefilters

(/jQuery.ajaxPrefilter/), transports (/jQuery.ajaxTransport/), and
converters that allow you to extend Ajax with a great deal of flexibility.

converters support mapping data types to other data types. If,

however, you want to map a custom data type to a known type (e.g
), you must add a correspondance between the response
Content-Type and the actual data type using the
option:

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

15 of 17

http://api.jquery.com/jquery.ajax/

This extra object is necessary because the response Content-Types and

data types never have a strict one-to-one correspondance (hence the
regular expression).
To convert from a supported type (e.g
,
) to a custom data
type and back again, use another pass-through converter:

The above now allows passing from

to
.

to

and then

Due to browser security restrictions, most "Ajax" requests are

subject to the same origin policy (http://en.wikipedia.org
/wiki/Same_origin_policy); the request can not successfully retrieve
data from a different domain, subdomain, port, or protocol.
Script and JSONP requests are not subject to the same origin
policy restrictions.

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

16 of 17

http://api.jquery.com/jquery.ajax/

9/11/2014 9:13 PM

jQuery.ajax() | jQuery API Documentation

http://api.jquery.com/jquery.ajax/

Learning jQuery
Fourth Edition

jQuery in Action

jQuery Succinctly

Bear Bibeault, Yehuda

Katz, and Aurelio De
Rosa

Cody Lindley

(http://www.syncfusion.com
Jonathan Chaffer
/resources
(http://www.manning.com
(http://www.packtpub.com
/techportal/ebooks
/derosa?a_aid=141d9491&
/learning-jquery/jquery?utm_medium=BizDeva_bid=bdd5b7ad)
with-simplejQuery.org0513)
javascripttechniques-fourthedition/book)
Karl Swedberg and

Copyright 2014 The jQuery Foundation (https://jquery.org

/team/). jQuery License (https://jquery.org/license/)

Learning Center (http://learn.jquery.com/)

Forum (http://forum.jquery.com/)

Web hosting by Media Temple (http://mediatemple.net) |

CDN by MaxCDN (http://www.maxcdn.com) |
Powered by WordPress (http://wordpress.org/) | Thanks:
Members (https://jquery.org/members/), Sponsors (https://jquery.org
/sponsors/)

17 of 17

API (http://api.jquery.com/)

IRC (http://irc.jquery.org/)
GitHub (https://github.com/jquery)

9/11/2014 9:13 PM