Userstack Getting Started: API Key and First Request (2026)

Getting started overview

Getting started with Userstack involves an initial setup phase to acquire the necessary credentials, followed by making an authenticated API call. Userstack provides a RESTful API that processes User-Agent strings to return structured data about the client device, operating system, and browser. The API's design emphasizes simplicity, requiring a single GET request with the User-Agent string and your API access key.

The process typically includes:

1. Account Creation: Registering for a Userstack account, which automatically provides an API key. A free tier is available for initial testing and low-volume applications, offering up to 10,000 requests per month.
2. API Key Retrieval: Locating your unique API key within the Userstack dashboard. This key is essential for authenticating all API requests.
3. First Request: Constructing and executing a basic API call using tools like cURL or one of the provided SDKs (PHP, Python, jQuery) to verify the setup.

This page focuses on these initial steps to ensure a successful first interaction with the Userstack API.

Create an account and get keys

To begin using Userstack, you must first create an account. This process is streamlined to provide immediate access to the API and your unique API key. Follow these steps to set up your account and retrieve your credentials:

1. Navigate to the Userstack Homepage: Visit the official Userstack website.
2. Sign Up: Locate the 'Sign Up' or 'Get API Key' button, typically prominent on the homepage. You will be prompted to provide an email address and create a password.
3. Account Confirmation: After signing up, you may receive an email to verify your account. Follow the instructions in the email to complete the registration process.
4. Access Your Dashboard: Once registered and logged in, you will be directed to your Userstack dashboard.
5. Retrieve Your API Key: Your unique API access key will be displayed prominently on your dashboard. This key is a string of alphanumeric characters, for example, YOUR_ACCESS_KEY_HERE. Keep this key secure, as it authenticates all your API requests. The Userstack API documentation provides further details on API key management.

The free tier provides 10,000 API requests per month, which is sufficient for development and testing. For higher volumes or additional features, Userstack offers various paid subscription plans.

Your first request

After obtaining your API key, you can make your first request to the Userstack API. The API is accessed via a simple HTTP GET request to a specific endpoint, including your API key and the User-Agent string you wish to analyze. The User-Agent string is a characteristic string that lets servers and network peers identify the application, operating system, vendor, and/or version of the requesting user agent. For example, a web browser sends its User-Agent string with every request, as described in MDN Web Docs on User-Agent header.

API Endpoint Structure

The base URL for the Userstack API is http://api.userstack.com/detect (for HTTP) or https://api.userstack.com/detect (for HTTPS, available on paid plans). Your API key is passed as a query parameter named access_key.

Example using cURL

cURL is a command-line tool and library for transferring data with URLs, commonly used for making HTTP requests. To make your first Userstack API call using cURL, replace YOUR_ACCESS_KEY_HERE with your actual API key and YOUR_USER_AGENT_STRING_HERE with the User-Agent string you want to detect.

curl "http://api.userstack.com/detect?access_key=YOUR_ACCESS_KEY_HERE&ua=YOUR_USER_AGENT_STRING_HERE"

A common User-Agent string to test with might be for a Chrome browser on Windows:

curl "http://api.userstack.com/detect?access_key=YOUR_ACCESS_KEY_HERE&ua=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"

The API response will be in JSON format, containing detailed information about the detected User-Agent string:

{
    "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
    "type": "browser",
    "brand": "Google Chrome",
    "name": "Chrome",
    "version": "124.0.0.0",
    "url": "https://www.google.com/chrome/",
    "device": {
        "brand": "Microsoft",
        "name": "Windows",
        "type": "desktop"
    },
    "os": {
        "name": "Windows",
        "version": "10",
        "code": "windows_10",
        "platform": "x64",
        "family": "Windows"
    },
    "client": {
        "type": "browser",
        "name": "Chrome",
        "version": "124.0.0.0",
        "engine": "Blink",
        "engine_version": "124.0.0.0"
    },
    "browser": {
        "name": "Chrome",
        "version": "124.0.0.0"
    }
}

Example using Python

Userstack provides official SDKs for several languages, including Python. To use the Python SDK, you would typically install it via pip:

pip install userstack-python

Then, you can make a request:

import userstack

access_key = 'YOUR_ACCESS_KEY_HERE'
ua_string = 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1'

client = userstack.Client(access_key)
result = client.detect(ua_string)

print(result)

This Python example will produce a similar JSON output, structured as a Python dictionary.

Example using PHP

For PHP, you can use the official Userstack PHP SDK. First, install it via Composer:

composer require userstack/userstack-php

Then, integrate it into your PHP script:

<?php
require_once 'vendor/autoload.php';

use Userstack\Client;

$access_key = 'YOUR_ACCESS_KEY_HERE';
$ua_string = 'Mozilla/5.0 (Linux; Android 10; SM-G973F) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36';

$client = new Client($access_key);
$result = $client->detect($ua_string);

print_r($result);
?>

The PHP script will output the detected User-Agent information as an associative array.

This table summarizes the initial steps:

Common next steps

Once you have successfully made your first Userstack API call, consider these common next steps to further integrate and optimize its use within your applications:

• Implement in Production Code: Integrate the API calls into your application's backend or frontend, depending on your architecture. Ensure your API key is handled securely, typically stored as an environment variable rather than hardcoded.
• Error Handling: Implement robust error handling for API responses. The Userstack documentation details various error codes and their meanings, such as invalid API keys or rate limit exceeded errors.
• Caching: For frequently requested User-Agent strings, implement a caching mechanism to reduce the number of API calls and improve response times. This can be particularly beneficial for high-traffic applications.
• HTTPS Endpoints: If you are on a paid plan, switch to the HTTPS endpoint (https://api.userstack.com/detect) for secure communication. This is crucial for protecting sensitive data and ensuring data integrity, as recommended by security best practices for Google Cloud's encryption in transit guidelines.
• Rate Limiting Management: Understand your plan's rate limits and implement strategies to manage them, such as exponential backoff for retries.
• Explore Full API Features: Review the Userstack API reference to understand all available parameters and response fields. This includes options for specifying fields, requesting a specific format, or using the lookup endpoint for IP address-based detection (if applicable to your plan).
• Monitor Usage: Regularly check your Userstack dashboard to monitor your API usage and ensure you stay within your plan's limits.
• Upgrade Plan: If your application's needs exceed the free tier or your current paid plan, consider upgrading to a higher-volume plan. Information on plan options is available on the Userstack pricing page.

Troubleshooting the first call

Encountering issues during your first API call is common. Here's a guide to troubleshoot some frequent problems:

Authentication Errors (Invalid API Key)

• Symptom: The API returns an error indicating an invalid access_key or authentication failure.
• Solution: Double-check that you have copied your API key precisely from your Userstack dashboard. Ensure there are no leading or trailing spaces and that the key is correctly passed as the access_key query parameter. The Userstack documentation on authentication provides examples.

Rate Limit Exceeded

• Symptom: The API returns an error indicating that you have exceeded your request limit.
• Solution: If you are on the free tier, you are limited to 10,000 requests per month. Check your dashboard for current usage. If you've hit the limit, wait for the next billing cycle or consider upgrading your Userstack subscription plan. For testing, ensure you aren't making excessive calls in a short period.

Incorrect Endpoint or Protocol

• Symptom: The request fails with a connection error or an unexpected response.
• Solution: Verify that you are using the correct API endpoint: http://api.userstack.com/detect for HTTP. If you are on a paid plan and attempting to use HTTPS, ensure you are using https://api.userstack.com/detect. Free accounts typically only support HTTP.

Missing User-Agent String

• Symptom: The API returns an error indicating a missing or invalid User-Agent string.
• Solution: Ensure the ua query parameter is present in your request and contains a valid User-Agent string. User-Agent strings can be long and complex; ensure they are correctly URL-encoded if necessary.

Network Issues

• Symptom: The request times out or fails to connect.
• Solution: Check your internet connection. If you are behind a corporate firewall, ensure that access to api.userstack.com is permitted.

SDK-Specific Issues

• Symptom: Errors when using one of the Userstack SDKs (PHP, Python, jQuery).
• Solution: Ensure the SDK is correctly installed and imported into your project. Verify that the SDK version is compatible with your environment. Consult the specific SDK documentation for installation and usage details.