TornAPI

Usage

Torn's API is split up in sections, with each section having their own unique selections. Selections can be combined, allowing you to query more data while only using a single API call.
Format for the url: https://api.torn.com/:SECTION/:ID?selections=:SELECTIONS&key=:KEY

Common Query Parameters

Query parameters are used to control the data your receive. Some of them are common on all selections or a lot of them.

Parameter	Description	Applicable
key	Required api key. Defines the owner and access level.	on every section
comment	Message to show in the api usage log. Every character over 10 will not be shown.	on every section
selections	Select what selections to pull data from. Providing no value will fall back to the default selection, if there is one. Supports multiple values, comma separated.	on every section
from	Limits results to have their timestamp after or on this timestamp.	where listed
to	Limits results to have their timestamp before or on this timestamp.	where listed
limit	Limits amount of results. Amount can't be above the default amount, will use default amount otherwise.	where listed
sort	Sort your results. Default will be descending.	where listed

Automatic Limits

In order to have the game and the api keep running smooth, Torn applies some limits on their api. These limits are all rolling limits, meaning that they don't have a specific reset point.

Call Limit

Each user can make up to 100 requests per minute across all of their keys. Multiple requests using invalid keys may result in a temporary IP ban - you must account for this by removing disabled or invalid keys upon error.

IP Limit

Alongside the call limit per user, there is also an IP limit of 1,000 calls a minute on a single IP.

Cloud Limit

Some data is stored in the cloud. Endpoints that pull that data have an additional limit of 50,000 rows a day (rolling 24 hours), for a specific category. These limits also exist in-game, but they are now separated and reaching the api limit will no longer. The different categories are faction news, events, activity log and personal stats.

Cache

Calls to the API are cached. This cache lasts 29 seconds, so you can space your calls 30 seconds between them. Changing the section, selection or id will have a different cache, but other parameters like to and from won't. Like always, there are exceptions to this which will be documented on the specific selections. You are NOT allowed to bypass the cache by using multiple API keys.

Access Levels

Which selections can be accessed using a specific API key depends on their access levels. There exist 4 predefined access levels, namely public, minimal access, limited access and full access.

It's also possible to create an API key with custom access, using https://www.torn.com/preferences.php#tab=api?step=addNewKey with query parameters. These parameters are title and the separate sections, like user, where the value is a comma-separated list of selections.
Example: https://www.torn.com/preferences.php#tab=api?step=addNewKey&title=TornAPI&user=basic,bars,cooldowns,notifications&faction=basic,contributors&torn=bank

Key Level
Public
Minimal Access
Limited Access
Full Access

user	property	faction	company	market	torn	key
ammo	lookup	applications	applications	bazaar	bank	info
attacks	property	armor	companies	itemmarket	cards
attacksfull	timestamp	armorynews	detailed	lookup	chainreport
bars		attacknews	employees	pointsmarket	cityshops
basic		attacks	lookup	timestamp	companies
battlestats		attacksfull	news		competition
bazaar		basic	profile		education
cooldowns		boosters	stock		factiontree
crimes		caches	timestamp		gyms
discord		cesium			honors
display		chain			itemdetails
education		chainreport			items
events		chains			itemstats
gym		contributors			logcategories
hof		crimeexp			logtypes
honors		crimenews			lookup
icons		crimes			medals
inventory		currency			organisedcrimes
jobpoints		donations			pawnshop
log		drugs			pokertables
lookup		fundsnews			properties
medals		lookup			rackets
merits		mainnews			raidreport
messages		medical			raids
missions		membershipnews			rankedwarreport
money		positions			rankedwars
networth		reports			searchforcash
newevents		revives			shoplifting
newmessages		revivesfull			stats
notifications		stats			stocks
perks		temporary			territory
personalstats		territory			territorynames
profile		territorynews			territorywarreport
properties		timestamp			territorywars
publicstatus		upgrades			timestamp
refills		weapons
reports
revives
revivesfull
skills
stocks
timestamp
travel
weaponexp
workstats

Error Codes

Code	Message	Description
0	Unknown error	Unhandled error, should not occur.
1	Key is empty	Private key is empty in current request.
2	Incorrect Key	Private key is wrong/incorrect format.
3	Wrong type	Requesting an incorrect basic type.
4	Wrong fields	Requesting incorrect selection fields.
5	Too many requests	Requests are blocked for a small period of time because of too many requests per user (max 100 per minute).
6	Incorrect ID	Wrong ID value.
7	Incorrect ID-entity relation	A requested selection is private (For example, personal data of another user / faction).
8	IP block	Current IP is banned for a small period of time because of abuse.
9	API disabled	Api system is currently disabled.
10	Key owner is in federal jail	Current key can't be used because owner is in federal jail.
11	Key change error	You can only change your API key once every 60 seconds.
12	Key read error	Error reading key from Database.
13	The key is temporarily disabled due to owner inactivity	The key owner hasn't been online for more than 7 days.
14	Daily read limit reached	Too many records have been pulled today by this user from our cloud services.
15	Temporary error	An error code specifically for testing purposes that has no dedicated meaning.
16	Access level of this key is not high enough	A selection is being called of which this key does not have permission to access.
17	Backend error occurred, please try again.
18	API key is paused