The Userstack API is a RESTful service that provides real-time parsing of User-Agent strings. It allows you to accurately detect a user's device, browser and operating system, so you can enhance user experiences, deliver tailored content and gain insights into your audience's technology usage.
API Access Key & Authentication
Obtain your API key: Sign up for a free or paid plan to start using the Userstack API. Once registered, your personal API Access Key will be available in the Dashboard. It is a 32-character key used to authenticate your requests.
Authenticate API requests: Append your access key to the endpoint using the access_key parameter:
https://api.apilayer.net/userstack/detect?access_key=YOUR_ACCESS_KEYYou can also send the key in the apikey request header instead. If you send both, the header is used.
Protect your API key: Your API key provides full access to your account, so keep it secure and private. Do not share it publicly. You can reset your key at any time from your Account Dashboard, which immediately invalidates the previous key.
API Response
When an API request is successful, Userstack returns a structured response with detailed information parsed from the submitted User-Agent string. Responses are delivered in JSON (default) or XML format and are divided into four main modules:
os– operating system detailsdevice– device type and manufacturer informationbrowser– browser name, version and rendering enginecrawler– bot and crawler detection (included on all plans, including Free)
In addition to these modules, the response includes the original User-Agent string and several general fields (type, brand, name, url).
Example API response (JSON):
{
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36",
"type": "browser",
"brand": "Apple",
"name": "Mac",
"url": "https://www.google.com/about/company/",
"os": {
"name": "macOS 10.14 Mojave",
"code": "macos_10_14",
"url": "https://en.wikipedia.org/wiki/MacOS_Mojave",
"family": "macOS",
"family_code": "macos",
"family_vendor": "Apple Inc.",
"icon": "https://assets.userstack.com/icons/os/macosx.png",
"icon_large": "https://assets.userstack.com/icons/os/macosx_big.png"
},
"device": {
"is_mobile_device": false,
"type": "desktop",
"brand": "Apple",
"brand_code": "apple",
"brand_url": "http://www.apple.com/",
"name": "Mac"
},
"browser": {
"name": "Chrome",
"version": "71.0.3578.98",
"version_major": "71",
"engine": "WebKit/Blink"
},
"crawler": {
"is_crawler": false,
"category": null,
"last_seen": null
}
}Please note: To fully illustrate a successful API request, crawler data has been included in the API response above. The crawler module is included on all plans, including Free.
Example API response (XML, with output=xml):
<?xml version="1.0"?>
<result>
<ua>Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36</ua>
<type>browser</type>
<brand>Apple</brand>
<name>Mac</name>
<url>https://www.google.com/about/company/</url>
<os>
<name>macOS 10.14 Mojave</name>
<code>macos_10_14</code>
<url>https://en.wikipedia.org/wiki/MacOS_Mojave</url>
<family>macOS</family>
<family_code>macos</family_code>
<family_vendor>Apple Inc.</family_vendor>
<icon>https://assets.userstack.com/icons/os/macosx.png</icon>
<icon_large>https://assets.userstack.com/icons/os/macosx_big.png</icon_large>
</os>
<device>
<is_mobile_device></is_mobile_device>
<type>desktop</type>
<brand>Apple</brand>
<brand_code>apple</brand_code>
<brand_url>http://www.apple.com/</brand_url>
<name>Mac</name>
</device>
<browser>
<name>Chrome</name>
<version>71.0.3578.98</version>
<version_major>71</version_major>
<engine>WebKit/Blink</engine>
</browser>
<crawler>
<is_crawler></is_crawler>
<category></category>
<last_seen></last_seen>
</crawler>
</result>Notes:
- The real XML response is one line; it is shown here with line breaks for readability.
- The root element is
<result>. For a bulk lookup, the root is<batch>with one<result index="N">per User-Agent. nullandfalsevalues are written as empty elements (for example<category></category>);trueis written as1.- Errors are always returned as JSON.
Example explained: The example above shows the response for a User-Agent string from an Apple Mac running macOS Mojave (10.14) and the Chrome browser (version 71).
API Endpoints
The Userstack API provides one endpoint, /detect, used for both Single Lookup and Bulk Lookup.
Single Lookup
Retrieve detailed information for a single User-Agent string. This is the most common use case and is ideal for real-time lookups within your application.
Example request:
https://api.apilayer.net/userstack/detect?access_key=YOUR_ACCESS_KEY&ua=Mozilla/5.0%20(Macintosh;%20Intel%20Mac%20OS%20X%2010_14_0)%20AppleWebKit/537.36%20(KHTML,%20like%20Gecko)%20Chrome/71.0.3578.98%20Safari/537.36Bulk Lookup (HTTP POST only)
Process up to 100 User-Agent strings in a single POST request to the same /detect endpoint. This is useful for analyzing logs or datasets with large volumes of User-Agent data. Each User-Agent in a successful bulk request counts as one request against your monthly quota. See API Features for the request format.
Note: Bulk lookups are available on the Professional plan and higher. On Free and Starter, 2 or more User-Agent strings return 400 with code 303 (batch_not_supported_on_plan).
256-bit HTTPS Encryption
All Userstack API requests support 256-bit SSL encryption to ensure secure data transmission. Connect to the API using the HTTPS protocol.
Example secure request:
https://api.apilayer.net/userstack/detectAvailable on: All Plans
Using HTTPS protects your API key and any sensitive data exchanged between your application and the Userstack servers.
JSONP Callbacks
The Userstack API supports JSONP (JSON with Padding) for cross-domain requests. To use this feature, append the callback parameter to your API request and set it to your preferred JavaScript function name, for example callback=CALLBACK_FUNCTION. The API returns the response wrapped inside that function call.
Example API request:
https://api.apilayer.net/userstack/detect?access_key=YOUR_ACCESS_KEY&ua=Mozilla/5.0%20(Macintosh;%20Intel%20Mac%20OS%20X%2010_14_0)%20AppleWebKit/537.36%20(KHTML,%20like%20Gecko)%20Chrome/71.0.3578.98%20Safari/537.36&callback=CALLBACK_FUNCTIONExample API response:
CALLBACK_FUNCTION({
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36",
"type": "browser",
"brand": "Apple",
"name": "Mac",
"url": "https://www.google.com/about/company/",
[...]
})Note: JSONP responses are in JSON format only (not XML). If the function name contains characters that are not allowed, the API returns plain JSON instead. The API also supports Access-Control (CORS) headers for cross-origin requests.
API Error Codes
If an API request fails, the API returns a JSON object describing the error. Some errors (missing_user_agent, too_many_user_agents) have no info field.
Example error response:
{
"success": false,
"error": {
"code": 303,
"type": "batch_not_supported_on_plan",
"info": "Bulk requests are not supported on your plan. Please upgrade your subscription."
}
}Common API Errors
| HTTP status | Code | Type | Description |
|---|---|---|---|
| 400 | 301 | missing_user_agent | No User-Agent string was provided (ua missing, empty or 0). |
| 400 | 301 | invalid_fields | None of the names in the fields parameter is valid. |
| 400 | 302 | too_many_user_agents | The bulk request contained more than 100 User-Agent strings. |
| 400 | 303 | batch_not_supported_on_plan | Bulk requests (2 or more User-Agent strings) are not supported on your plan. |
| 404 | 103 | invalid_api_function | The requested API function does not exist. |
| 401 | – | – | Missing API key (No API key found in request) or invalid API key (Unauthorized), returned by the API gateway. |
| 429 | – | – | Monthly quota or overage limit reached (Plan limit reached – upgrade for more requests.), returned by the API gateway. |
See API Error Codes for the errors shared by all APIs.