API Reference

hsr

Classes:

• HSRClient –

  Client to interact with the Hakushin Honkai Star Rail API.

T module-attribute

T = TypeVar('T', bound=EndgameBaseModel)

HSRClient

Client to interact with the Hakushin Honkai Star Rail API.

Methods:

• calculate_hsr_enemy_stats –

  Calculate enemy stats for both halves of an Endgame stage from already fetched endgame detail.

• fetch_apoc –

  Fetch a list of Apocalyptic Shadow (Apoc) event summaries.

• fetch_apoc_detail –

  Fetch detailed stage and wave data for a specific Apocalyptic Shadow event.

• fetch_character_detail –

  Fetch the details of a Honkai Star Rail character.

• fetch_characters –

  Fetch all Honkai Star Rail characters.

• fetch_elite_and_hard_level_groups –

  Download and structure EliteGroup and HardLevelGroup data from a JavaScript module.

• fetch_light_cone_detail –

  Fetch the details of a Honkai Star Rail light cone.

• fetch_light_cones –

  Fetch all Honkai Star Rail light cones.

• fetch_moc –

  Fetch a list of Memory of Chaos (MoC) event summaries.

• fetch_moc_detail –

  Fetch detailed stage and wave data for a specific Memory of Chaos event.

• fetch_monsters –

  Fetch all Honkai Star Rail monsters.

• fetch_monsters_detail –

  Fetch the full detail of a specific monster.

• fetch_pf –

  Fetch a list of Pure Fiction (PF) event summaries.

• fetch_pf_detail –

  Fetch detailed stage and wave data for a specific Pure Fiction event.

• fetch_relic_set_detail –

  Fetch the details of a Honkai Star Rail relic set.

• fetch_relic_sets –

  Fetch all Honkai Star Rail relic sets.

calculate_hsr_enemy_stats async

calculate_hsr_enemy_stats(
    endgame_data: EndgameBaseModel,
    *,
    egs: dict[int, EliteGroup],
    hlgs: dict[tuple[int, int], HardLevelGroup],
    stage_num: int = 0,
) -> list[list[list[ProcessedEnemy]]]

Calculate enemy stats for both halves of an Endgame stage from already fetched endgame detail.

Parameters:

• endgame_data

  (EndgameBaseModel) –

  The already fetched Endgame detail object (e.g., MemoryOfChaosDetail).

• egs

  (dict[int, EliteGroup]) –

  A dictionary of elite groups keyed by their IDs, get it from fetch_elite_and_hard_level_groups.

• hlgs

  (dict[tuple[int, int], HardLevelGroup]) –

  A dictionary of hard level groups keyed by (HardLevelGroup ID, Level), get it from fetch_elite_and_hard_level_groups.

• stage_num

  (int, default: 0 ) –

  The 0-indexed stage number within the endgame (defaults to 0).

Returns:

• list[list[list[ProcessedEnemy]]] –

  A list containing two elements—one for each half of the stage.

• list[list[list[ProcessedEnemy]]] –

  Each half is a list of waves, and each wave is a list of HSREnemy objects

• list[list[list[ProcessedEnemy]]] –

  (or None if a matching child monster variant cannot be found).

• list[list[list[ProcessedEnemy]]] –

  The structure is: [ [ # First half [HSREnemy, HSREnemy, ...], # Wave 1 [HSREnemy, HSREnemy, ...], # Wave 2 ], [ # Second half ... ] ]

Referenced by:

• API Reference Clients API Reference  hsr  HSRClient
  •  fetch_apoc_detail
  •  fetch_moc_detail
  •  fetch_pf_detail

fetch_apoc async

fetch_apoc(
    *, use_cache: bool = True
) -> list[EndgameSummary]

Fetch a list of Apocalyptic Shadow (Apoc) event summaries.

Parameters:

• use_cache

  (bool, default: True ) –

  Whether to use the response cache.

Returns:

• list[EndgameSummary] –

  A list of EndgameSummary objects for each Apocalyptic Shadow event.

fetch_apoc_detail async

fetch_apoc_detail(
    apoc_id: int,
    *,
    full: Literal[False] = ...,
    use_cache: bool = ...,
) -> ApocDetail

fetch_apoc_detail(
    apoc_id: int,
    *,
    full: Literal[True] = ...,
    use_cache: bool = ...,
) -> FullApocDetail

fetch_apoc_detail(
    apoc_id: int,
    *,
    full: bool = False,
    use_cache: bool = True,
) -> ApocDetail | FullApocDetail

Fetch detailed stage and wave data for a specific Apocalyptic Shadow event.

Parameters:

• apoc_id

  (int) –

  The ID of the Apocalyptic Shadow event.

• use_cache

  (bool, default: True ) –

  Whether to use the response cache.

• full

  (bool, default: False ) –

  If True, return calculated ProcessedEnemy stats instead of the raw model.

Returns:

• ApocDetail | FullApocDetail –

  FullApocDetail if full=True, otherwise ApocDetail.

Note

When full=True, this method performs additional stat calculation using calculate_hsr_enemy_stats and replaces enemy ID lists with ProcessedEnemy models directly on the wave objects.

fetch_character_detail async

fetch_character_detail(
    character_id: int, *, use_cache: bool = True
) -> CharacterDetail

Fetch the details of a Honkai Star Rail character.

Parameters:

• character_id

  (int) –

  The character ID.

• use_cache

  (bool, default: True ) –

  Whether to use the response cache.

Returns:

• CharacterDetail –

  The character details object.

fetch_characters async

fetch_characters(
    *, use_cache: bool = True, version: str | None = None
) -> list[Character]

Fetch all Honkai Star Rail characters.

Parameters:

• use_cache

  (bool, default: True ) –

  Whether to use the response cache.

• version

  (str | None, default: None ) –

  The version of the characters to fetch.

Returns:

• list[Character] –

  A list of character objects.

fetch_elite_and_hard_level_groups async

fetch_elite_and_hard_level_groups(
    use_cache: bool = True,
) -> tuple[
    dict[int, EliteGroup],
    dict[tuple[int, int], HardLevelGroup],
]

Download and structure EliteGroup and HardLevelGroup data from a JavaScript module.

Returns:

• tuple[dict[int, EliteGroup], dict[tuple[int, int], HardLevelGroup]] –

  A tuple of: - dict[int, EliteGroup]: keyed by EliteGroup ID - dict[tuple[int, int], HardLevelGroup]: keyed by (HardLevelGroup, Level)

Referenced by:

• API Reference Clients API Reference  hsr  HSRClient  calculate_hsr_enemy_stats

fetch_light_cone_detail async

fetch_light_cone_detail(
    light_cone_id: int, *, use_cache: bool = True
) -> LightConeDetail

Fetch the details of a Honkai Star Rail light cone.

Parameters:

• light_cone_id

  (int) –

  The light cone ID.

• use_cache

  (bool, default: True ) –

  Whether to use the response cache.

Returns:

• LightConeDetail –

  The light cone details object.

fetch_light_cones async

fetch_light_cones(
    *, use_cache: bool = True, version: str | None = None
) -> list[LightCone]

Fetch all Honkai Star Rail light cones.

Parameters:

• use_cache

  (bool, default: True ) –

  Whether to use the response cache.

• version

  (str | None, default: None ) –

  The version of the light cones to fetch.

Returns: A list of light cone objects.

fetch_moc async

fetch_moc(
    *, use_cache: bool = True
) -> list[EndgameSummary]

Fetch a list of Memory of Chaos (MoC) event summaries.

Parameters:

• use_cache

  (bool, default: True ) –

  Whether to use the response cache.

Returns:

• list[EndgameSummary] –

  A list of EndgameSummary objects for each MoC event.

fetch_moc_detail async

fetch_moc_detail(
    moc_id: int,
    *,
    full: Literal[False] = ...,
    use_cache: bool = ...,
) -> MOCDetail

fetch_moc_detail(
    moc_id: int,
    *,
    full: Literal[True] = ...,
    use_cache: bool = ...,
) -> FullMOCDetail

fetch_moc_detail(
    moc_id: int,
    *,
    full: bool = False,
    use_cache: bool = True,
) -> MOCDetail | FullMOCDetail

Fetch detailed stage and wave data for a specific Memory of Chaos event.

Parameters:

• moc_id

  (int) –

  The ID of the Memory of Chaos event to retrieve.

• use_cache

  (bool, default: True ) –

  If True, use a cached response if available.

• full

  (bool, default: False ) –

  If True, automatically resolve and attach ProcessedEnemy stats to each wave in the stage data. If False, return raw model data.

Returns:

• MOCDetail | FullMOCDetail –

  FullMOCDetail if full=True, otherwise MOCDetail.

Note

When full=True, this method performs additional stat calculation using calculate_hsr_enemy_stats and replaces enemy ID lists with ProcessedEnemy models directly on the wave objects.

fetch_monsters async

fetch_monsters(*, use_cache: bool = True) -> list[Monster]

Fetch all Honkai Star Rail monsters.

Parameters:

• use_cache

  (bool, default: True ) –

  Whether to use the response cache.

Returns:

• list[Monster] –

  A list of monster objects.

fetch_monsters_detail async

fetch_monsters_detail(
    monster_id: int, *, use_cache: bool = True
) -> MonsterDetail

Fetch the full detail of a specific monster.

Parameters:

• monster_id

  (int) –

  The ID of the monster to retrieve.

• use_cache

  (bool, default: True ) –

  Whether to use the response cache.

Returns:

• MonsterDetail –

  A MonsterDetail object containing the full monster stats and metadata.

fetch_pf async

fetch_pf(*, use_cache: bool = True) -> list[EndgameSummary]

Fetch a list of Pure Fiction (PF) event summaries.

Parameters:

• use_cache

  (bool, default: True ) –

  Whether to use the response cache.

Returns:

• list[EndgameSummary] –

  A list of EndgameSummary objects for each Pure Fiction event.

fetch_pf_detail async

fetch_pf_detail(
    pf_id: int,
    *,
    full: Literal[False] = ...,
    use_cache: bool = ...,
) -> PFDetail

fetch_pf_detail(
    pf_id: int,
    *,
    full: Literal[True] = ...,
    use_cache: bool = ...,
) -> FullPFDetail

fetch_pf_detail(
    pf_id: int,
    *,
    full: bool = False,
    use_cache: bool = True,
) -> PFDetail | FullPFDetail

Fetch detailed stage and wave data for a specific Pure Fiction event.

Parameters:

• pf_id

  (int) –

  The ID of the Pure Fiction event.

• use_cache

  (bool, default: True ) –

  Whether to use the response cache.

• full

  (bool, default: False ) –

  If True, return calculated ProcessedEnemy stats instead of the raw model.

Returns:

• PFDetail | FullPFDetail –

  FullPFDetail if full=True, otherwise PFDetail.

Note

When full=True, this method performs additional stat calculation using calculate_hsr_enemy_stats and replaces enemy ID lists with ProcessedEnemy models directly on the wave objects.

fetch_relic_set_detail async

fetch_relic_set_detail(
    set_id: int, *, use_cache: bool = True
) -> RelicSetDetail

Fetch the details of a Honkai Star Rail relic set.

Parameters:

• set_id

  (int) –

  The relic set ID.

• use_cache

  (bool, default: True ) –

  Whether to use the response cache.

Returns:

• RelicSetDetail –

  The relic set details object.

fetch_relic_sets async

fetch_relic_sets(
    *, use_cache: bool = True, version: str | None = None
) -> list[RelicSet]

Fetch all Honkai Star Rail relic sets.

Parameters:

• use_cache

  (bool, default: True ) –

  Whether to use the response cache.

• version

  (str | None, default: None ) –

  The version of the relic sets to fetch.

Returns: A list of relic set objects.