onlyscavs/TARKOV_DEV_API.md

tarkov.dev GraphQL API Reference

Community-made, real-time EFT data. No API key required.

• Endpoint: https://api.tarkov.dev/graphql
• Playground: https://api.tarkov.dev/ (interactive explorer with autocomplete)
• Protocol: GraphQL over HTTP POST
• Auth: None — completely open
• Source: https://github.com/the-hideout/tarkov-api

---

How to query (Python)

import requests

API_URL = "https://api.tarkov.dev/graphql"

def gql(query):
    r = requests.post(API_URL, json={"query": query})
    r.raise_for_status()
    data = r.json()
    if "errors" in data:
        raise RuntimeError(data["errors"])
    return data["data"]

---

Common arguments (most queries accept these)

Arg	Type	Notes
lang	LanguageCode	e.g. en, ru, de, fr, es, zh
gameMode	GameMode	regular or pve
limit	Int	Max results to return
offset	Int	Pagination offset

---

All available root queries

achievements(lang, limit, offset)
ammo(lang, gameMode, limit, offset)
archivedItemPrices(id, limit, offset)
barters(lang, gameMode, limit, offset)
bosses(lang, gameMode, name, limit, offset)
crafts(lang, gameMode, limit, offset)
fleaMarket(lang, gameMode)
goonReports(lang, gameMode, limit, offset)
handbookCategories(lang, limit, offset)
hideoutStations(lang, gameMode, limit, offset)
historicalItemPrices(id, days, lang, gameMode, limit, offset)
item(id, normalizedName, lang, gameMode)
items(ids, name, names, type, types, categoryNames, handbookCategoryNames, bsgCategoryId, bsgCategoryIds, bsgCategory, lang, gameMode, limit, offset)
itemCategories(lang, limit, offset)
itemPrices(id, gameMode, limit, offset)
lootContainers(lang, limit, offset)
maps(lang, gameMode, name, enemies, limit, offset)
mastering(lang)
playerLevels()
prestige(lang, gameMode)
questItems(lang)
skills(lang)
stationaryWeapons(lang, limit, offset)
status()
task(id, lang, gameMode)
tasks(faction, lang, gameMode, limit, offset)
traders(lang, gameMode, limit, offset)

---

Query examples

Server status

{
  status {
    currentStatuses {
      name
      message
      status
    }
    messages {
      time
      type
      content
      solveTime
    }
  }
}

Single item by name

{
  items(name: "colt m4a1") {
    id
    name
    shortName
    basePrice
    avg24hPrice
    changeLast48hPercent
    width
    height
    weight
    wikiLink
    iconLink
    gridImageLink
    sellFor {
      price
      currency
      source
    }
    buyFor {
      price
      currency
      source
    }
  }
}

Items by type (e.g. all keys)

{
  items(types: [keys]) {
    id
    name
    shortName
    wikiLink
    gridImageLink
    properties {
      ... on ItemPropertiesKey {
        uses
      }
    }
  }
}

Valid ItemType values include: keys, ammo, armor, backpack, gun, headwear, rig, medical, food, barter, container, grenade, headphones, knife, stimulator, suppressor, weapon

All tasks / quests

{
  tasks {
    id
    name
    wikiLink
    minPlayerLevel
    kappaRequired
    trader {
      name
    }
    taskRequirements {
      task {
        id
        name
      }
      status
    }
    objectives {
      id
      type
      description
      maps {
        name
        normalizedName
      }
      ... on TaskObjectiveItem {
        item { name shortName }
        count
        foundInRaid
      }
      ... on TaskObjectiveShoot {
        targetNames
        count
      }
      ... on TaskObjectiveLocation {
        locationNames
      }
      ... on TaskObjectiveQuestItem {
        questItem { name }
        count
      }
      ... on TaskObjectiveSkill {
        skillLevel { name level }
      }
      ... on TaskObjectiveTraderLevel {
        trader { name }
        level
      }
    }
    startRewards {
      items { item { name } count }
      traderStanding { trader { name } standing }
    }
    finishRewards {
      items { item { name } count }
      experience
      traderStanding { trader { name } standing }
      offerUnlock { trader { name } item { name } }
    }
  }
}

Note: objectives returns a TaskObjective interface — use inline fragments (... on TypeName) to access type-specific fields.

Single task by ID

{
  task(id: "5936d90786f7742b1420ba5b") {
    name
    trader { name }
    taskRequirements { task { id name } }
  }
}

Ammo stats

{
  ammo {
    item { name shortName }
    caliber
    damage
    armorDamage
    penetrationPower
    penetrationChance
    fragmentationChance
    initialSpeed
    lightBleedModifier
    heavyBleedModifier
  }
}

Traders

{
  traders {
    id
    name
    normalizedName
    currency { name }
    levels {
      level
      requiredPlayerLevel
      requiredReputation
      requiredCommerce
      cashOffers {
        item { name }
        price
        currency
        minTraderLevel
        taskUnlock { name }
      }
    }
    barters {
      requiredItems { item { name } count }
      rewardItems { item { name } count }
      minTraderLevel
      taskUnlock { name }
    }
  }
}

Hideout stations

{
  hideoutStations {
    id
    name
    levels {
      level
      constructionTime
      itemRequirements { item { name } count }
      stationLevelRequirements { station { name } level }
      skillRequirements { skill { name } level }
      traderRequirements { trader { name } requirementType value }
      bonuses { type value }
    }
  }
}

Maps

{
  maps {
    id
    name
    normalizedName
    raidDuration
    players
    bosses {
      boss { name }
      spawnChance
      spawnLocations { name chance }
      escorts { boss { name } amount { count chance } }
    }
    extracts {
      name
      faction
      switches { name }
    }
  }
}

Crafts

{
  crafts {
    station { name }
    level
    duration
    requiredItems { item { name } count }
    rewardItems { item { name } count }
    taskUnlock { name }
  }
}

Barters

{
  barters {
    trader { name }
    level
    taskUnlock { name }
    requiredItems { item { name } count }
    rewardItems { item { name } count }
  }
}

Flea market info

{
  fleaMarket {
    enabled
    minPlayerLevel
    sellOfferFeeRate
    sellRequirementFeeRate
  }
}

Achievements

{
  achievements {
    id
    name
    description
    hidden
    rarity
    playersCompletedPercent
    side
  }
}

Goon reports (roaming boss locations)

{
  goonReports {
    map { name }
    timestamp
  }
}

---

Key types reference

Item fields

id, name, shortName, normalizedName
basePrice, avg24hPrice, low24hPrice, high24hPrice
changeLast48h, changeLast48hPercent
lastLowPrice, lastOfferCount
width, height, weight, velocity
wikiLink, iconLink, gridImageLink, inspectImageLink, image8xLink
types[]           – ItemType enum values this item belongs to
sellFor[]         – { price, currency, source, vendor { name } }
buyFor[]          – { price, currency, source, vendor { name } }
bartersFor[]      – Barter objects
bartersUsing[]    – Barter objects
usedInTasks[]     – Task objects
receivedFromTasks[] – Task objects
properties        – ItemProperties union (see below)
category          – { id, name }

ItemProperties union types

Use ... on ItemPropertiesX { } inline fragments:

• ItemPropertiesKey → uses
• ItemPropertiesAmmo → caliber, damage, penetrationPower, ...
• ItemPropertiesArmor → class, durability, material, zones[]
• ItemPropertiesArmorAttachment → class, durability, material, zones[], headCoverage
• ItemPropertiesBackpack → capacity, grids[]
• ItemPropertiesChestRig → capacity, class, durability, zones[]
• ItemPropertiesWeapon → caliber, fireRate, ergonomics, recoil...
• ItemPropertiesMagazine → capacity, caliber, ergonomics
• ItemPropertiesScope → ergonomics, recoil, zoomLevels[]
• ItemPropertiesMedKit → uses, useTime, hpCostLightBleeding, hpCostHeavyBleeding
• ItemPropertiesFood → energy, hydration, stimEffects[]
• ItemPropertiesStimulator → stimEffects[]
• ItemPropertiesHelmet → class, durability, material, headZones[], deafening
• ItemPropertiesGlasses → class, durability, blindnessProtection
• ItemPropertiesNightVision → intensity, noiseIntensity, noiseScale
• ItemPropertiesContainer → capacity
• ItemPropertiesGrenade → type, fuse, fragments, minExplosionDistance, maxExplosionDistance

Task / quest fields

id, name, normalizedName
wikiLink
minPlayerLevel
kappaRequired         – bool, whether needed for Kappa (The Collector)
restartable
trader { id, name }
map { id, name }      – nullable, map-specific tasks only
experience
taskRequirements[]    – { task { id, name }, status[] }
objectives[]          – TaskObjective interface (use inline fragments)
startRewards          – TaskRewards
finishRewards         – TaskRewards

TaskRewards fields

items[]            – { item { name }, count }
traderStanding[]   – { trader { name }, standing }
offerUnlock[]      – { trader { name }, level, item { name } }
skillLevelReward[] – { name, level }
craftUnlock[]      – craft objects

---

How we use it in this project

Script	Query	Purpose
import_keys.py	items(types: [keys])	Fetches all key items into keys table
import_quests.py	tasks { id name wikiLink trader taskRequirements }	Fetches all tasks and their dependencies into quests + quest_deps tables

The Collector prerequisite tree is computed from quest_deps using a recursive SQL CTE in app.py at /collector.