Instance and PGCR Data

Overview

Every raid activity in Destiny 2 generates a unique instance identified by an instance ID. RaidHub tracks these instances and provides detailed information including player performance, completion status, modifiers, and more.

What is an Instance?

An instance represents a single playthrough of a raid activity. Each instance has:

A unique instance ID (64-bit integer)
Completion status and timing information
Player roster and individual statistics
Activity modifiers and skull hashes
Scoring and ranking information

What is a PGCR?

A PGCR (Post Game Carnage Report) is the raw data from Bungie’s API containing detailed statistics about an activity. RaidHub stores compressed PGCRs and provides two ways to access instance data:

Instance Extended (/instance/{instanceId}) - RaidHub’s formatted view with additional metadata
Raw PGCR (/pgcr/{instanceId}) - Bungie’s original PGCR data

Getting Instance Details

Use the /instance/{instanceId} endpoint to get comprehensive instance information.

Basic Instance Request

curl "https://api.raid.report/v2/instance/12345678901234567"

Instance Properties

Core Instance Data

instanceId

string

Unique identifier for the instance

hash

integer

Activity version hash

activityId

integer

Activity definition ID

versionId

integer

Version definition ID

completed

boolean

Whether the activity was completed

playerCount

integer

Number of players in the instance

score

integer

Total score (for scored activities)

Special Completion Flags

fresh

boolean

Whether this was a fresh clear (no encounter checkpoints used)

flawless

boolean

Whether the run was flawless (no player deaths)

isDayOne

boolean

Whether completed during the Day One period (typically first 24 hours)

isContest

boolean

Whether completed during contest mode period

isWeekOne

boolean

Whether completed during the first week

isBlacklisted

boolean

Whether the instance has been flagged/blacklisted

Timing Information

dateStarted

string

ISO 8601 timestamp when the activity started

dateCompleted

string

ISO 8601 timestamp when the activity completed

duration

integer

Total duration in seconds

season

integer

Destiny 2 season ID when the activity occurred

Additional Instance Data

platformType

integer

Platform where the activity occurred (1=Xbox, 2=PSN, 3=Steam, etc.)

skullHashes

array

Array of modifier hashes applied to the activity

leaderboardRank

integer | null

The instance’s rank on relevant leaderboards (if applicable)

metadata

object

Activity metadata including activityName, versionName, and isRaid

Understanding Instance Players

Each instance includes detailed player information in the players array.

Player Data Structure

{
  "completed": true,
  "isFirstClear": false,
  "sherpas": 42,
  "timePlayedSeconds": 3245,
  "playerInfo": {
    "membershipId": "4611686018484930134",
    "membershipType": 3,
    "displayName": "PlayerName",
    "bungieGlobalDisplayName": "PlayerName",
    "bungieGlobalDisplayNameCode": 1234
  },
  "characters": [
    {
      "characterId": "2305843009504575107",
      "classHash": 2271682572,
      "emblemHash": 1234567890,
      "completed": true,
      "timePlayedSeconds": 3245,
      "startSeconds": 0,
      "score": 0,
      "kills": 234,
      "assists": 45,
      "deaths": 3,
      "precisionKills": 123,
      "superKills": 12,
      "grenadeKills": 23,
      "meleeKills": 8,
      "weapons": [
        {
          "weaponHash": 1234567890,
          "kills": 67,
          "precisionKills": 45
        }
      ]
    }
  ]
}

Player Fields

completed

boolean

Whether the player completed the activity

isFirstClear

boolean

Whether this was the player’s first clear of this activity

sherpas

integer

Number of sherpa runs this player has across all activities

timePlayedSeconds

integer

Total time the player spent in the activity

characters

array

Array of characters the player used (players can switch characters mid-raid)

Character Statistics

Each character entry includes combat statistics:

Performance: kills, assists, deaths, precision kills
Ability usage: super kills, grenade kills, melee kills
Weapons: detailed weapon statistics with kills and precision kills
Class info: class hash and emblem hash
Timing: time played on this specific character

Getting Raw PGCRs

Use the /pgcr/{instanceId} endpoint to get the raw Post Game Carnage Report from Bungie’s API.

Raw PGCR Request

curl "https://api.raid.report/v2/pgcr/12345678901234567"

PGCR vs Instance Extended

Instance Extended
Raw PGCR

Use /instance/{instanceId} when you want:

RaidHub’s formatted data structure
Additional metadata (activity names, leaderboard ranks)
Simplified player and character data
Fresh/flawless/day-one flags
Better integration with other RaidHub endpoints

Cache Duration: 5 minutes (300 seconds)

Use /pgcr/{instanceId} when you want:

Raw Bungie API data format
Access when Bungie’s API is down
Maximum detail from original PGCR
Compatibility with Bungie API tools
Minimal RaidHub processing

Cache Duration: 24 hours (86400 seconds)

The PGCR endpoint is useful as a fallback when Bungie’s API is experiencing issues, since RaidHub caches all PGCRs.

Common Use Cases

Analyzing a Raid Completion

Get the instance data

Fetch the instance using /instance/{instanceId}

Check completion flags

Examine completed, fresh, flawless to determine completion type

Analyze performance

Look at duration, player stats, and weapon usage

Display results

Show activity name, completion time, and player roster

Finding Flawless Runs

// Check if an instance was flawless
const response = await fetch(
  `https://api.raid.report/v2/instance/${instanceId}`
);
const instance = await response.json();

if (instance.flawless && instance.completed) {
  console.log('Flawless completion!');
  console.log(`Completed in ${Math.floor(instance.duration / 60)} minutes`);
  
  // Show all players who participated
  instance.players.forEach(player => {
    console.log(`- ${player.playerInfo.displayName}`);
  });
}

Examining Player Performance

const response = await fetch(
  `https://api.raid.report/v2/instance/${instanceId}`
);
const instance = await response.json();

// Analyze each player's combat stats
instance.players.forEach(player => {
  const totalKills = player.characters.reduce(
    (sum, char) => sum + char.kills, 0
  );
  const totalDeaths = player.characters.reduce(
    (sum, char) => sum + char.deaths, 0
  );
  const kd = totalDeaths > 0 ? (totalKills / totalDeaths).toFixed(2) : totalKills;
  
  console.log(`${player.playerInfo.displayName}: ${totalKills} kills, ${totalDeaths} deaths (${kd} K/D)`);
});

Checking Activity Modifiers

const response = await fetch(
  `https://api.raid.report/v2/instance/${instanceId}`
);
const instance = await response.json();

if (instance.skullHashes && instance.skullHashes.length > 0) {
  console.log('Active modifiers:', instance.skullHashes);
  // You can look up these hashes in the Destiny 2 manifest
  // to get the actual modifier names
}

Finding Day One Completions

const response = await fetch(
  `https://api.raid.report/v2/instance/${instanceId}`
);
const instance = await response.json();

if (instance.isDayOne) {
  console.log('Day One completion!');
  console.log('Completed at:', new Date(instance.dateCompleted));
  
  if (instance.leaderboardRank) {
    console.log('World rank:', instance.leaderboardRank);
  }
}

Analyzing Weapon Usage

const response = await fetch(
  `https://api.raid.report/v2/instance/${instanceId}`
);
const instance = await response.json();

// Aggregate weapon kills across all players
const weaponStats = new Map();

instance.players.forEach(player => {
  player.characters.forEach(char => {
    char.weapons.forEach(weapon => {
      const current = weaponStats.get(weapon.weaponHash) || { kills: 0, precisionKills: 0 };
      weaponStats.set(weapon.weaponHash, {
        kills: current.kills + weapon.kills,
        precisionKills: current.precisionKills + weapon.precisionKills
      });
    });
  });
});

// Find most used weapons
const sortedWeapons = [...weaponStats.entries()]
  .sort((a, b) => b[1].kills - a[1].kills)
  .slice(0, 5);

console.log('Top 5 weapons by kills:');
sortedWeapons.forEach(([hash, stats]) => {
  console.log(`Weapon ${hash}: ${stats.kills} kills (${stats.precisionKills} precision)`);
});

Instance from Player History

Instance IDs can be obtained from a player’s activity history:

// Get player's recent activities
const historyResponse = await fetch(
  `https://api.raid.report/v2/player/${membershipId}/history?count=10`
);
const history = await historyResponse.json();

// Get details for the most recent activity
const latestInstanceId = history.activities[0].instanceId;
const instanceResponse = await fetch(
  `https://api.raid.report/v2/instance/${latestInstanceId}`
);
const instanceDetails = await instanceResponse.json();

console.log('Latest activity:', instanceDetails.metadata.activityName);
console.log('Completed:', instanceDetails.completed);

Error Handling

Common Errors

404 - InstanceNotFoundError

error

The specified instance ID does not exist in the RaidHub database

404 - PGCRNotFoundError

error

The PGCR data for this instance is not available

Example Error Response

{
  "error": true,
  "code": "InstanceNotFoundError",
  "message": "Instance not found",
  "instanceId": "12345678901234567"
}

Not all instances have complete data. Older instances or those from private activities may have limited information.

Understanding Character Switching

Players can switch characters during a raid. The characters array tracks each character used:

const player = instance.players[0];

if (player.characters.length > 1) {
  console.log(`${player.playerInfo.displayName} switched characters:`);
  player.characters.forEach((char, index) => {
    console.log(`Character ${index + 1}: ${char.timePlayedSeconds}s playtime`);
  });
}

Characters are ordered by:

Completion status (completed characters first)
Time played (most time played first)

Best Practices

Cache Instance Data

Instance data rarely changes. Cache responses for 5+ minutes.

Use Instance Extended

Prefer /instance over /pgcr for better metadata and formatting

Handle Missing Data

Some fields may be null or empty, especially for older instances

Check Blacklist Status

The isBlacklisted flag indicates suspicious or invalid completions

Player History

Get a player’s activity history to find instance IDs

Leaderboards

Find top instances on contest and speed leaderboards

Get Started

Core Concepts

Guides

​Overview

​What is an Instance?

​What is a PGCR?

​Getting Instance Details

​Basic Instance Request

​Instance Properties

​Core Instance Data

​Special Completion Flags

​Timing Information

​Additional Instance Data

​Understanding Instance Players

​Player Data Structure

​Player Fields

​Character Statistics

​Getting Raw PGCRs

​Raw PGCR Request

​PGCR vs Instance Extended

​Common Use Cases

​Analyzing a Raid Completion

​Finding Flawless Runs

​Examining Player Performance

​Checking Activity Modifiers

​Finding Day One Completions

​Analyzing Weapon Usage

​Instance from Player History

​Error Handling

​Common Errors

​Example Error Response

​Understanding Character Switching

​Best Practices

Cache Instance Data

Use Instance Extended

Handle Missing Data

Check Blacklist Status

​Related Endpoints

Player History

Leaderboards

Build docs developers (and LLMs) love

Overview

What is an Instance?

What is a PGCR?

Getting Instance Details

Basic Instance Request

Instance Properties

Core Instance Data

Special Completion Flags

Timing Information

Additional Instance Data

Understanding Instance Players

Player Data Structure

Player Fields

Character Statistics

Getting Raw PGCRs

Raw PGCR Request

PGCR vs Instance Extended

Common Use Cases

Analyzing a Raid Completion

Finding Flawless Runs

Examining Player Performance

Checking Activity Modifiers

Finding Day One Completions

Analyzing Weapon Usage

Instance from Player History

Error Handling

Common Errors

Example Error Response

Understanding Character Switching

Best Practices

Related Endpoints