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. Custom keys have access to all public selections.
Example: https://www.torn.com/preferences.php#tab=api?step=addNewKey&title=TornAPI&user=basic,bars,cooldowns,notifications&faction=basic,contributors&torn=bank

We provide a key builder for making those links easier.

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
criminalrecord		cesium			gyms
discord		chain			honors
display		chainreport			itemdetails
education		chains			items
equipment		contributors			itemstats
events		crimeexp			logcategories
gym		crimenews			logtypes
hof		crimes			lookup
honors		currency			medals
icons		donations			organisedcrimes
inventory		drugs			pawnshop
jobpoints		fundsnews			pokertables
log		lookup			properties
lookup		mainnews			rackets
medals		medical			raidreport
merits		membershipnews			raids
messages		positions			rankedwarreport
missions		rankedwars			rankedwars
money		reports			rockpaperscissors
networth		revives			searchforcash
newevents		revivesfull			shoplifting
newmessages		stats			stats
notifications		temporary			stocks
perks		territory			territory
personalstats		territorynews			territorynames
profile		timestamp			territorywarreport
properties		upgrades			territorywars
publicstatus		weapons			timestamp
refills
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 has been paused by the owner.
19	Must be migrated to crimes 2.0.
20	Race not yet finished.
21	Incorrect category	Wrong cat value.