Endpoints
Context API Access and Setup
The Spur Context API provides a lookup capability for individual IP addresses. By default, the data returned by our API reflects what we know at this moment. It is a real-time representation of our IP address data. Historical lookups are available on Pro plans and above, with a token that has the Context API Historical Query permission.
All Context API authentication is performed using a Token header.
https://api.spur.us
Don't have a token yet?
Visit the Spur dashboard and purchase a subscription today!
Query Arguments
| Code | Description |
|---|---|
dt | A datetime in the format YYYYmmdd. Only valid for tokens with the Context API Historical Query permission (Pro plans and above). |
mmgeo | A boolean value, that when set to 1, will return MaxMind's GeoLite2 geolocation data instead of Spur's geolocation data in the location object. |
Response Codes
| Code | Description |
|---|---|
200 | The request succeeded. |
400 | Bad input provided; IP must be a public IPv4 or IPv6 address. |
401 | The token is invalid, has been rotated or deleted, or doesn't have permission for this endpoint. |
403 | The token was revoked, or the account is disabled. Contact support@spur.us. |
429 | This token, or your account, has no queries left for this billing period. |
500 | An error occurred. |
Response Headers
| Code | Description |
|---|---|
x-balance-remaining | The number of queries this token can still make: your account's remaining queries for the billing period, or the token's Limit if that's lower. |
x-result-dt | The date for which this response is sourced in the format YYYYmmdd. When performing historical lookups, this date indicates that the IP context response is from the YYYYmmdd data feed. |
The IP Context Object
The IP Context Object summarizes all available information for an IP address. It is provided as a single dictionary. All fields not explicitly marked as required may be omitted if their value is null.
Attributes
A top-level field describing AI activity that has been observed from this IP address.
Spur IP GeoBGP autonomous system information.
The organization currently assigned to use the specific IP address, such as a customer, hosting provider, or service operator.
Descriptive data about the connecting client.
Infrastructure type.
IPv4 address associated with the connection.
Spur IP Geo location information of the IP.
List of identified risk factors or behaviors.
List of services or protocols in use (e.g., OPENVPN, IPSEC).
Information about tunneling methods (VPN, TOR, etc.) used.
{"as": {"number": 49981,"organization": "WorldStream"},"client": {"behaviors": ["FILE_SHARING", "TOR_PROXY_USER"],"concentration": {"city": "Polāia Kalān","country": "IN","density": 0.2675,"geohash": "tsn","skew": 6762,"state": "Madhya Pradesh"},"count": 4,"countries": 2,"proxies": ["ABCPROXY_PROXY", "9PROXY_PROXY", "NETNUT_PROXY", "GOPROXY_PROXY"],"spread": 4724209,"types": ["MOBILE", "DESKTOP"]},"infrastructure": "DATACENTER","ip": "89.39.106.191","location": {"city": "Amsterdam","country": "NL","state": "North Holland"},"organization": "WorldStream B.V.","risks": ["CALLBACK_PROXY", "TUNNEL", "GEO_MISMATCH"],"services": ["OPENVPN"],"tunnels": [{"anonymous": true,"entries": ["89.39.106.82"],"operator": "PROTON_VPN","type": "VPN"}]}
Lookup an IP Address
Retrieves an IP Context Object by IPv4 or IPv6 address. An IP Context Object summarizes all available information about the queried IP address. Some fields are optional and will be omitted if not available.
curl https://api.spur.us/v2/context/89.39.106.191 \-H "Token: $SPUR_TOKEN"
{"as": {"number": 49981,"organization": "WorldStream"},"client": {"behaviors": ["FILE_SHARING", "TOR_PROXY_USER"],"concentration": {"city": "Polāia Kalān","country": "IN","density": 0.2675,"geohash": "tsn","skew": 6762,"state": "Madhya Pradesh"},"count": 4,"countries": 2,"proxies": ["ABCPROXY_PROXY", "9PROXY_PROXY", "NETNUT_PROXY", "GOPROXY_PROXY"],"spread": 4724209,"types": ["MOBILE", "DESKTOP"]},"infrastructure": "DATACENTER","ip": "89.39.106.191","location": {"city": "Amsterdam","country": "NL","state": "North Holland"},"organization": "WorldStream B.V.","risks": ["CALLBACK_PROXY", "TUNNEL", "GEO_MISMATCH"],"services": ["OPENVPN"],"tunnels": [{"anonymous": true,"entries": ["89.39.106.82"],"operator": "PROTON_VPN","type": "VPN"}]}
Lookup a historical IP Address
Retrieves an IP Context Object by IPv4 or IPv6 address for the specified date. An IP Context Object summarizes all available information about the queried IP address. Some fields are optional and will be omitted if not available.
Historical lookups need a token with the Context API Historical Query permission, available on Pro plans and above. Without it, the API returns
401.
curl https://api.spur.us/v2/context/89.39.106.191?dt=20251026 \-H "Token: $SPUR_TOKEN"
{"as": {"number": 49981,"organization": "WorldStream"},"client": {"behaviors": ["FILE_SHARING", "TOR_PROXY_USER"],"concentration": {"city": "Polāia Kalān","country": "IN","density": 0.2675,"geohash": "tsn","skew": 6762,"state": "Madhya Pradesh"},"count": 4,"countries": 2,"proxies": ["ABCPROXY_PROXY", "9PROXY_PROXY", "NETNUT_PROXY", "GOPROXY_PROXY"],"spread": 4724209,"types": ["MOBILE", "DESKTOP"]},"infrastructure": "DATACENTER","ip": "89.39.106.191","location": {"city": "Amsterdam","country": "NL","state": "North Holland"},"organization": "WorldStream B.V.","risks": ["CALLBACK_PROXY", "TUNNEL", "GEO_MISMATCH"],"services": ["OPENVPN"],"tunnels": [{"anonymous": true,"entries": ["89.39.106.82"],"operator": "PROTON_VPN","type": "VPN"}]}
The Tag Metadata Object
The Tag Metadata Object includes analysis, statistics, and metrics for a service tag.
Attributes
Whether Spur actively tracks this service or tag.
Maximum age, in days, for observations associated with this service.
All tags associated with this service, including aliases or related tag identifiers.
Alternative tags or names associated with this service.
Canonical tag that this tag aliases.
Services or tags that resell this service.
Services or tags that this service resells or routes through.
Whether the service allows access to local network resources.
Indicates whether white-label or rebranded versions of the service exist.
Product categories for bandwidth reselling and routing.
A free-text description of the service or entity.
Whether the service or infrastructure primarily aims to anonymize user traffic.
Whether the service includes callback or reverse-proxy functionalities.
Whether the service or platform is oriented toward enterprise usage.
Whether the service is currently inactive or defunct.
Whether the service claims a 'no logging' policy.
Human-readable name of the service or entity.
Operating systems and environments supported by this service.
Protocols or services used for network traffic.
Unique identifier or tag for this service or entity.
Possible granularities for configuring a service exit or route.
Primary website or homepage for the service.
{"allTags": ["OXYLABS_PROXY"],"allowsWhiteLabel": true,"categories": ["RESIDENTIAL_PROXY", "DATACENTER_PROXY", "MOBILE_PROXY", "ISP_PROXY"],"description": "OxyLabs is the second largest proxy provider tracked. Their users are sourced through SDKs embedded in mobile applications and browser extensions. These users are likely unaware that they agreed to contribute to this proxy network.","isAnonymous": true,"isCallbackProxy": true,"isNoLog": true,"isTracked": true,"maxAgeDays": 3,"metrics": {"averageDeviceCount": 33.18324032745378,"churnRate": 0.08311564645065442,"distinctASNs": 25981,"distinctCountries": 235,"distinctIPs": 9923953,"distinctISPs": 75902},"name": "Oxylabs","platforms": ["ROUTER"],"protocols": ["HTTP", "SOCKS"],"resells": [],"aliases": [],"resoldBy": ["BLANKPROXIES_PROXY", "SMARTPROXY_PROXY", "IPBURGER_PROXY"],"tag": "OXYLABS_PROXY","targetingTypes": ["CITY", "STATE", "COUNTRY", "ASN"],"website": "https://oxylabs.io"}
Lookup Tag Metadata
Retrieves a Tag Metadata Object which contains a summary of metrics and information for the provided tag.
curl https://api.spur.us/v2/metadata/tags/OXYLABS_PROXY \-H "Token: $SPUR_TOKEN"
{"allTags": ["OXYLABS_PROXY"],"allowsWhiteLabel": true,"categories": ["RESIDENTIAL_PROXY", "DATACENTER_PROXY", "MOBILE_PROXY", "ISP_PROXY"],"description": "Oxylabs is the second largest proxy provider tracked. Their users are sourced through SDKs embedded in mobile applications and browser extensions. These users are likely unaware that they agreed to contribute to this proxy network.","isAnonymous": true,"isCallbackProxy": true,"isNoLog": true,"isTracked": true,"maxAgeDays": 3,"metrics": {"averageDeviceCount": 33.18324032745378,"churnRate": 0.08311564645065442,"distinctASNs": 25981,"distinctCountries": 235,"distinctIPs": 9923953,"distinctISPs": 75902},"name": "Oxylabs","platforms": ["ROUTER"],"protocols": ["HTTP", "SOCKS"],"resoldBy": ["BLANKPROXIES_PROXY", "SMARTPROXY_PROXY", "IPBURGER_PROXY"],"tag": "OXYLABS_PROXY","targetingTypes": ["CITY", "STATE", "COUNTRY", "ASN"]}
Lookup API Token Status
Retrieves the status of your API token, the number of queries it can still make, and your service tier. The token needs the Context API permission, so a token with only a data feed permission gets 401. Checking status doesn't use a query.
curl https://api.spur.us/status \-H "Token: $SPUR_TOKEN"
{"active": true,"queriesRemaining": 49283,"serviceTier": "online"}
FAQs
Have a question that's not answered here? Search our Knowledgebase.