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.

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		dirtybombs
cooldowns		boosters	stock		education
crimes		caches	timestamp		factiontree
discord		cesium			gyms
display		chain			honors
education		chainreport			itemdetails
equipment		chains			items
events		contributors			itemstats
gym		crimeexp			logcategories
hof		crimenews			logtypes
honors		crimes			lookup
icons		currency			medals
inventory		donations			organisedcrimes
jobpoints		drugs			pawnshop
log		fundsnews			pokertables
lookup		lookup			properties
medals		mainnews			rackets
merits		medical			raidreport
messages		membershipnews			raids
missions		positions			rankedwarreport
money		rankedwars			rankedwars
networth		reports			rockpaperscissors
newevents		revives			searchforcash
newmessages		revivesfull			shoplifting
notifications		stats			stats
perks		temporary			stocks
personalstats		territory			territory
profile		territorynews			territorynames
properties		timestamp			territorywarreport
publicstatus		upgrades			territorywars
refills		weapons			timestamp
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