Torn Stats API Documentation

[GET] https://www.tornstats.com/api/v1/{key}
Polls the Torn API with the key and checks to see if there's a matching account with the Torn ID on Torn Stats. This will update the User's API key with the one matching the request if the key is valid. 
        {
    "status": true,
    "message": "User already exists. No action necessary."
}
[GET] https://www.tornstats.com/api/v1/{key}/loot
Displays the NPC loot times. 
        {
    "4": {
        "name": "DUKE",
        "torn_id": 4,
        "status": "Hospital",
        "hosp_out": 1616198996,
        "loot_2": 1616200796,
        "loot_3": 1616204396,
        "loot_4": 1616211596,
        "loot_5": 1616225996,
        "updated": 1616229508
    },
    "15": {
        "name": "Leslie",
        "torn_id": 15,
        "status": "Hospital",
        "hosp_out": 1616202508,
        "loot_2": 1616204308,
        "loot_3": 1616207908,
        "loot_4": 1616215108,
        "loot_5": 1616229508,
        "updated": 1616229508
    },
    "19": {
        "name": "Jimmy",
        "torn_id": 19,
        "status": "Okay",
        "hosp_out": 1616195003,
        "loot_2": 1616196803,
        "loot_3": 1616200403,
        "loot_4": 1616207603,
        "loot_5": 1616222003,
        "updated": 1616229508
    },
    "20": {
        "name": "Fernando",
        "torn_id": 20,
        "status": "Okay",
        "hosp_out": 1616195488,
        "loot_2": 1616197288,
        "loot_3": 1616200888,
        "loot_4": 1616208088,
        "loot_5": 1616222488,
        "updated": 1616229508
    },
    "status": true,
    "message": "NPCs found."
}
[GET] https://www.tornstats.com/api/v1/{key}/faction/crimes
Displays relevant OC details about faction members. 
        {
    "status": true,
    "message": "Member crime stats found.",
    "members": {
        "776": {
            "natural_nerve": 60,
            "crime_success": 9,
            "psych_degree": 1,
            "federal_judge": 1,
            "verified": 1
        },
        "1990": {
            "natural_nerve": 55,
            "crime_success": 0,
            "psych_degree": 1,
            "federal_judge": 1,
            "verified": 0
        },
        "456123": {
            "natural_nerve": 60,
            "crime_success": 0,
            "psych_degree": 1,
            "federal_judge": 0,
            "verified": 1
        },
        "123456": {
            "natural_nerve": 60,
            "crime_success": 10,
            "psych_degree": 1,
            "federal_judge": 1,
            "verified": 1
        }
    }
}
[GET] https://www.tornstats.com/api/v1/{key}/faction/roster
Display roster details about your faction. 
        {
    "status": true,
    "message": "Member details found.",
    "members": {
        "776": {
            "name": "IceBlueFire",
            "total": 123456,
            "verified": 1
        },
        "790": {
            "name": "Shapeshifter",
            "total": 123456,
            "verified": 1
        },
        "2926": {
            "name": "Icy",
            "total": 123456,
            "verified": 1
        },
    }
}
[GET] https://www.tornstats.com/api/v1/{key}/events
Displays your latest events on Torn Stats. 
        {
    "status": true,
    "events": [
        {
            "timestamp": 1613153932,
            "event": "IceBlueFire [776] has requested you take 1 member from JFK.",
            "seen": 1
        },
        {
            "timestamp": 1613153901,
            "event": "IceBlueFire [776] has requested you take 2 members from JFK.",
            "seen": 1
        }
    ]
}
[GET] https://www.tornstats.com/api/v1/{key}/battlestats/record
Updates player's battle stats and returns the gain since last update. 
        {
    "age": "3 minutes ago",
    "status": true,
    "message": "Updated stats for 776",
    "deltaStrength": 0,
    "deltaDefense": 0,
    "deltaDexterity": 0,
    "deltaSpeed": 0
}
[GET] https://www.tornstats.com/api/v1/{key}/hof/[1/0]
Updates the player's preference of participating in sharing their battle stats anonymously. 
        {
    "status": true,
    "message": "You have turned sharing on! Thank you for participating anonymously."
}
[GET] https://www.tornstats.com/api/v1/{key}/settings&comparespy=[1/0]&comparepersonal=[1/0]&personalstats=xantaken,attackswon,refills,statenhancersused
Updates the player's preferences for comparing details on profiles.
spy decides whether to display spy details or not.
comparespy decides whether to display the stat differences in spies.
comparepersonal decides whether to display personal stats or not.
personalstats is a comma separated string of API-friendly references to personal stats. The order in which they're entered in the string is the order in which they'll appear on profiles. 
        {
    "status": true,
    "message": "Your settings have been updated!"
}
[GET] https://www.tornstats.com/api/v1/{key}/spy/{target}
Loads profile details about the target. Accepts the Torn ID or the Torn Name as the target. 
        {
    "compare": {
        "status": true,
        "data": {
            "Xanax Taken": {
                "amount": 1245,
                "difference": 0
            },
            "Refills": {
                "amount": 164,
                "difference": 0
            },
            "Stat Enhancers Used": {
                "amount": 1,
                "difference": 0
            },
            "Merits Bought": {
                "amount": 10,
                "difference": 0
            },
            "Attacks Won": {
                "amount": 1654,
                "difference": 0
            },
            "Defends Won": {
                "amount": 45,
                "difference": 0
            },
            "Networth": {
                "amount": 100000000,
                "difference": 0
            }
        },
        "timestamp": "1533752540",
        "spy": {
            "type": "faction-share",
            "status": true,
            "message": "Shared stats found.",
            "target_score": 30.251259169,
            "your_score": 30.251259169,
            "fair_fight_bonus": 3,
            "difference": "18 hours ago",
            "strength": 100,
            "deltaStrength": 0,
            "defense": 100,
            "deltaDefense": 0,
            "speed": 100,
            "deltaSpeed": 0,
            "dexterity": 100,
            "deltaDexterity": 0,
            "total": 400,
            "deltaTotal": 0
        },
        "attacks": {
            "status": false,
            "message": "No recent attacks made against this player."
        }
    }
}
type will indicate whether it was a faction-spy, personal-spy, or faction-share (indicating they're in the faction)
[GET] https://www.tornstats.com/api/v1/{key}/battlestats/graph
Gets up to 3 months worth of stat data to build a graph out of. 
        {
    "status": true,
    "message": "Stats found.",
    "share_hof": "1",
    "data": [
        {
            "strength": 100,
            "defense": 100,
            "speed": 100,
            "dexterity": 100,
            "timestamp": 1525910400,
            "total": 400
        },
        {
            "strength": 130,
            "defense": 130,
            "speed": 100,
            "dexterity": 100,
            "timestamp": 1525996800,
            "total": 460
        },
        {
            "strength": 130,
            "defense": 130,
            "speed": 130,
            "dexterity": 100,
            "timestamp": 1526083200,
            "total": 520
        },
        {
            "strength": 130,
            "defense": 130,
            "speed": 130,
            "dexterity": 1000,
            "timestamp": 1526169600,
            "total": 1390
        },
        {
            "strength": 130,
            "defense": 130,
            "speed": 130,
            "dexterity": 1000,
            "timestamp": 1526256000,
            "total": 1390
        }
    ]
}
[POST] https://www.tornstats.com/api/v1/{key}/store/spy
Post must include the following parameters: 'player_id', 'player_name', 'player_level' The other optional parameters are: 'strength', 'defense', 'speed', 'dexterity', 'total', 'player_faction' To enter faction spies, the user must have the faction permission (API Save Spies) or be a Faction Assistant or above. 
        {
    "faction_entered": true,
    "personal_entered": true,
    "status": true,
    "message": "Spy has been saved. Stats have been updated for IceBlueFire in JFK's spies. Stats have been updated for IceBlueFire in JFK 2.1's spies. Stats have been updated for IceBlueFire in your personal spies."
}
Change Log:
  • Changed the spy end point. The url changed from /{KEY}/spy/{USER_ID} to /{KEY}/spy/user/{USER_ID}
  • Added support to get spies for a full roster at /{KEY}/spy/faction/{FACTION_ID}
[GET] https://www.tornstats.com/api/v2/{key}
Polls the Torn API with the key and checks to see if there's a matching account with the Torn ID on Torn Stats. This will update the User's API key with the one matching the request if the key is valid. 
        {
    "status": true,
    "message": "User already exists. No action necessary."
}
[GET] https://www.tornstats.com/api/v2/{key}/loot
Displays the NPC loot times. 
        {
    "4": {
        "name": "DUKE",
        "torn_id": 4,
        "status": "Hospital",
        "hosp_out": 1616198996,
        "loot_2": 1616200796,
        "loot_3": 1616204396,
        "loot_4": 1616211596,
        "loot_5": 1616225996,
        "updated": 1616229508
    },
    "15": {
        "name": "Leslie",
        "torn_id": 15,
        "status": "Hospital",
        "hosp_out": 1616202508,
        "loot_2": 1616204308,
        "loot_3": 1616207908,
        "loot_4": 1616215108,
        "loot_5": 1616229508,
        "updated": 1616229508
    },
    "19": {
        "name": "Jimmy",
        "torn_id": 19,
        "status": "Okay",
        "hosp_out": 1616195003,
        "loot_2": 1616196803,
        "loot_3": 1616200403,
        "loot_4": 1616207603,
        "loot_5": 1616222003,
        "updated": 1616229508
    },
    "20": {
        "name": "Fernando",
        "torn_id": 20,
        "status": "Okay",
        "hosp_out": 1616195488,
        "loot_2": 1616197288,
        "loot_3": 1616200888,
        "loot_4": 1616208088,
        "loot_5": 1616222488,
        "updated": 1616229508
    },
    "status": true,
    "message": "NPCs found."
}
[GET] https://www.tornstats.com/api/v2/{key}/efficiency{?man=xxx&int=xxx&end=xxx}
Displays your employee efficiency at every company position. If man/int/end aren't passed, it'll use the work stats of the key owner. 
        {
    "1": {
        "company": "Hair Salon",
        "Stylist": 165,
        "Colorist": 161,
        "Nail Technician": 165,
        "Apprentice": 181,
        "Shampooist": 171,
        "Senior Stylist": 155,
        "Receptionist": 157,
        "Trainer": 149,
        "Aesthetician": 149
        },
    ...
    "stats": {
        "manual_labor": 100000,
        "intelligence": 100000,
        "endurance": 300000
    },
    "status": true,
    "message": "Retrieving employee efficiency with assumed education completed."
}
[GET] https://www.tornstats.com/api/v2/{key}/faction/crimes
Displays relevant OC details about faction members. 
        {
    "status": true,
    "message": "Member crime stats found.",
    "members": {
        "776": {
            "natural_nerve": 60,
            "crime_success": 9,
            "psych_degree": 1,
            "federal_judge": 1,
            "verified": 1
        },
        "1990": {
            "natural_nerve": 55,
            "crime_success": 0,
            "psych_degree": 1,
            "federal_judge": 1,
            "verified": 0
        },
        "456123": {
            "natural_nerve": 60,
            "crime_success": 0,
            "psych_degree": 1,
            "federal_judge": 0,
            "verified": 1
        },
        "123456": {
            "natural_nerve": 60,
            "crime_success": 10,
            "psych_degree": 1,
            "federal_judge": 1,
            "verified": 1
        }
    }
}
[GET] https://www.tornstats.com/api/v2/{key}/faction/roster
Display roster details about your faction. 
        {
    "status": true,
    "message": "Member details found.",
    "members": {
        "776": {
            "name": "IceBlueFire",
            "total": 123456,
            "verified": 1
        },
        "790": {
            "name": "Shapeshifter",
            "total": 123456,
            "verified": 1
        },
        "2926": {
            "name": "Icy",
            "total": 123456,
            "verified": 1
        },
    }
}
[GET] https://www.tornstats.com/api/v2/{key}/wars/{war_id}
Displays spy details for the rosters in a specific war 
        {
    "status": true,
    "message": "War data found.",
    "war": {
        "id": 243,
        "war_id": 337,
        "faction_a_id": 21041,
        "faction_a_name": "URANUS",
        "faction_a_score": 2388,
        "faction_a_chain": 0,
        "faction_b_id": 37933,
        "faction_b_name": "Sell Swords",
        "faction_b_score": 2079,
        "faction_b_chain": 0,
        "start": 1642784400,
        "start_at": "2022-01-21T17:00:00.000000Z",
        "end": 0,
        "end_at": "-000001-11-30T00:00:00.000000Z",
        "target": 1110,
        "winner": 0,
        "created_at": "2022-01-19T09:01:02.000000Z",
        "updated_at": "2022-01-25T14:27:02.000000Z",
        "faction_a_reward_respect": 0,
        "faction_a_reward_points": 0,
        "faction_a_end_rank": null,
        "faction_b_reward_respect": 0,
        "faction_b_reward_points": 0,
        "faction_b_end_rank": null
    },
    "faction_a": {
        "ID": 21041,
        "name": "URANUS",
        "tag": "URNS",
        "tag_image": "21041-92649.png",
        "leader": 2425885,
        "co-leader": 0,
        "respect": 64318,
        "age": 3805,
        "capacity": 25,
        "best_chain": 58,
        "territory_wars": [],
        "raid_wars": [],
        "peace": [],
        "rank": {
            "level": 1,
            "name": "Unranked",
            "division": 0,
            "position": 0
        },
        "members": {
            ...
        }
    },
    "faction_b": {
        "ID": 37933,
        "name": "Sell Swords",
        "tag": "S/S",
        "tag_image": "37933-32820.png",
        "leader": 2144083,
        "co-leader": 2148320,
        "respect": 143361,
        "age": 1853,
        "capacity": 40,
        "best_chain": 100,
        "territory_wars": [],
        "raid_wars": [],
        "peace": [],
        "rank": {
            "level": 2,
            "name": "Bronze",
            "division": 0,
            "position": 0
        },
        "members": {
            ...
        }
    }
}
[GET] https://www.tornstats.com/api/v2/{key}/faction/skills
Displays skills for faction members or yourself if not in a faction. 
        {
 	"status": true,
 	"message": "Faction member skills found.",
 	"members": {
 		"776": {
 			"hunting": 96.27,
 			"reviving": 100,
 			"racing": 100,
 			"bootlegging": 100,
 			"burglary": 100,
 			"graffiti": 100,
 			"pickpocketing": 100,
 			"search_for_cash": 100,
 			"shoplifting": 100,
 			"card_skimming": 100,
 			"hustling": 100,
 			"disposal": 100,
 			"cracking": 100,
 			"forgery": 100,
 			"scamming": 100,
 			"updated_at": "2024-10-13T23:37:16.000000Z"
 		},
 		"778": {
 			...
 		},
 	}
}
[GET] https://www.tornstats.com/api/v2/{key}/events
Displays your latest events on Torn Stats. 
        {
    "status": true,
    "events": [
        {
            "timestamp": 1613153932,
            "event": "IceBlueFire [776] has requested you take 1 member from JFK.",
            "seen": 1
        },
        {
            "timestamp": 1613153901,
            "event": "IceBlueFire [776] has requested you take 2 members from JFK.",
            "seen": 1
        }
    ]
}
[GET] https://www.tornstats.com/api/v2/{key}/battlestats/record
Updates player's battle stats and returns the gain since last update. 
        {
    "age": "3 minutes ago",
    "status": true,
    "message": "Updated stats for 776",
    "deltaStrength": 0,
    "deltaDefense": 0,
    "deltaDexterity": 0,
    "deltaSpeed": 0
}
[GET] https://www.tornstats.com/api/v2/{key}/hof/[1/0]
Updates the player's preference of participating in sharing their battle stats anonymously. 
        {
    "status": true,
    "message": "You have turned sharing on! Thank you for participating anonymously."
}
[GET] https://www.tornstats.com/api/v2/{key}/settings&comparespy=[1/0]&comparepersonal=[1/0]&personalstats=xantaken,attackswon,refills,statenhancersused
Updates the player's preferences for comparing details on profiles.
spy decides whether to display spy details or not.
comparespy decides whether to display the stat differences in spies.
comparepersonal decides whether to display personal stats or not.
personalstats is a comma separated string of API-friendly references to personal stats. The order in which they're entered in the string is the order in which they'll appear on profiles. 
        {
    "status": true,
    "message": "Your settings have been updated!"
}
[GET] https://www.tornstats.com/api/v2/{key}/spy/user/{user_id}
Loads profile details about the target. Accepts the Torn ID or the Torn Name as the target. 
        {
    "compare": {
        "status": true,
        "data": {
            "Xanax Taken": {
                "amount": 1245,
                "difference": 0
            },
            "Refills": {
                "amount": 164,
                "difference": 0
            },
            "Stat Enhancers Used": {
                "amount": 1,
                "difference": 0
            },
            "Merits Bought": {
                "amount": 10,
                "difference": 0
            },
            "Attacks Won": {
                "amount": 1654,
                "difference": 0
            },
            "Defends Won": {
                "amount": 45,
                "difference": 0
            },
            "Networth": {
                "amount": 100000000,
                "difference": 0
            }
        },
        "timestamp": "1533752540",
        "spy": {
            "type": "faction-share",
            "status": true,
            "message": "Shared stats found.",
            "target_score": 30.251259169,
            "your_score": 30.251259169,
            "fair_fight_bonus": 3,
            "difference": "18 hours ago",
            "strength": 100,
            "deltaStrength": 0,
            "defense": 100,
            "deltaDefense": 0,
            "speed": 100,
            "deltaSpeed": 0,
            "dexterity": 100,
            "deltaDexterity": 0,
            "total": 400,
            "deltaTotal": 0
        },
        "attacks": {
            "status": false,
            "message": "No recent attacks made against this player."
        }
    }
}
type will indicate whether it was a faction-spy, personal-spy, or faction-share (indicating they're in the faction)
[GET] https://www.tornstats.com/api/v2/{key}/spy/faction/{faction_id}
Loads profile details about the target. Accepts the Torn ID or the Torn Name as the target. 
        {
    "status": true,
    "message": "Spy data found.",
    "faction": {
        "ID": 8989,
        "name": "JUX HQ",
        "tag": "JUX",
        "tag_image": "8989-31756.png",
        "leader": 271665,
        "co-leader": 1629262,
        "respect": 6821922,
        "age": 4843,
        "capacity": 100,
        "best_chain": 25000,
        "territory_wars": [],
        "raid_wars": [],
        "peace": [],
        "rank": {
        "level": 3,
        "name": "Bronze",
        "division": 1,
        "position": 0
    },
    "members": {
        "790": {
            "name": "Shapeshifter",
            "level": 79,
            "days_in_faction": 439,
            "last_action": {
            "status": "Offline",
            "timestamp": 1642453772,
            "relative": "54 minutes ago"
        },
        "status": {
            "description": "Okay",
            "details": "",
            "state": "Okay",
            "color": "green",
            "until": 0
        },
        "position": "Step Sibling",
        "id": 790,
        "personalstats": {
            "Xanax Taken": 469,
            "Stat Enhancers Used": 1,
            "Refills": 15,
            "Attacks Won": 675,
            "Defends Won": 95,
            "Networth": 7586851691,
            "Defends Lost": 1243,
            "Elo Rating": 1387,
            "timestamp": 1627302167
        }
    },
    ...
}
type will indicate whether it was a faction-spy, personal-spy, or faction-share (indicating they're in the faction)
[GET] https://www.tornstats.com/api/v2/{key}/battlestats/graph
Gets up to 3 months worth of stat data to build a graph out of. 
        {
    "status": true,
    "message": "Stats found.",
    "share_hof": "1",
    "data": [
        {
            "strength": 100,
            "defense": 100,
            "speed": 100,
            "dexterity": 100,
            "timestamp": 1525910400,
            "total": 400
        },
        {
            "strength": 130,
            "defense": 130,
            "speed": 100,
            "dexterity": 100,
            "timestamp": 1525996800,
            "total": 460
        },
        {
            "strength": 130,
            "defense": 130,
            "speed": 130,
            "dexterity": 100,
            "timestamp": 1526083200,
            "total": 520
        },
        {
            "strength": 130,
            "defense": 130,
            "speed": 130,
            "dexterity": 1000,
            "timestamp": 1526169600,
            "total": 1390
        },
        {
            "strength": 130,
            "defense": 130,
            "speed": 130,
            "dexterity": 1000,
            "timestamp": 1526256000,
            "total": 1390
        }
    ]
}
[POST] https://www.tornstats.com/api/v2/{key}/store/spy
Post must include the following parameters: 'player_id', 'player_name', 'player_level' The other optional parameters are: 'strength', 'defense', 'speed', 'dexterity', 'total', 'player_faction', 'timestamp' To enter faction spies, the user must have the faction permission (API Save Spies) or be a Faction Assistant or above. 
        {
    "faction_entered": true,
    "personal_entered": true,
    "status": true,
    "message": "Spy has been saved. Stats have been updated for IceBlueFire in JFK's spies. Stats have been updated for IceBlueFire in JFK 2.1's spies. Stats have been updated for IceBlueFire in your personal spies."
}

Status:

Most operations can check for this flag to decide whether the response is good or not.

Rate Limit:

This API is rate limited to 100 calls per minute. You can check the response headers for how many calls before timed out.
Visit one of our sponsors:
View All Banners | Advertise Here
Banner

If you have any questions or problems, please contact a staff member on Torn Stats' Discord.

Any individual player's data will not be reviewed beyond security or maintenance reasons.