API Reference

HSRClient

Bases: BaseClient

Client to interact with the Hakushin Honkai Star Rail API.

calculate_hsr_enemy_stats(endgame_data, *, egs, hlgs, stage_num=0) async

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

Parameters:

Name	Type	Description	Default
endgame_data	EndgameBaseModel	The already fetched Endgame detail object (e.g., MemoryOfChaosDetail).	required
egs	dict[int, EliteGroup]	A dictionary of elite groups keyed by their IDs, get it from fetch_elite_and_hard_level_groups.	required
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.	required
stage_num	int	The 0-indexed stage number within the endgame (defaults to 0).	0

Returns:

Type	Description
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 ... ] ]

fetch_apoc(*, use_cache=True) async

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

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use the response cache.	True

Returns:

Type	Description
list[EndgameSummary]	A list of EndgameSummary objects for each Apocalyptic Shadow event.

fetch_apoc_detail(apoc_id, *, full=False, use_cache=True) async

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

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

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

Parameters:

Name	Type	Description	Default
apoc_id	int	The ID of the Apocalyptic Shadow event.	required
use_cache	bool	Whether to use the response cache.	True
full	bool	If True, return calculated ProcessedEnemy stats instead of the raw model.	False

Returns:

Type	Description
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(character_id, *, use_cache=True) async

Fetch the details of a Honkai Star Rail character.

Parameters:

Name	Type	Description	Default
character_id	int	The character ID.	required
use_cache	bool	Whether to use the response cache.	True

Returns:

Type	Description
CharacterDetail	The character details object.

fetch_characters(*, use_cache=True) async

Fetch all Honkai Star Rail characters.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use the response cache.	True

Returns:

Type	Description
list[Character]	A list of character objects.

fetch_elite_and_hard_level_groups(use_cache=True) async

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

Returns:

Type	Description
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)

fetch_light_cone_detail(light_cone_id, *, use_cache=True) async

Fetch the details of a Honkai Star Rail light cone.

Parameters:

Name	Type	Description	Default
light_cone_id	int	The light cone ID.	required
use_cache	bool	Whether to use the response cache.	True

Returns:

Type	Description
LightConeDetail	The light cone details object.

fetch_light_cones(*, use_cache=True) async

Fetch all Honkai Star Rail light cones.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use the response cache.	True

Returns:

Type	Description
list[LightCone]	A list of light cone objects.

fetch_moc(*, use_cache=True) async

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

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use the response cache.	True

Returns:

Type	Description
list[EndgameSummary]	A list of EndgameSummary objects for each MoC event.

fetch_moc_detail(moc_id, *, full=False, use_cache=True) async

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

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

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

Parameters:

Name	Type	Description	Default
moc_id	int	The ID of the Memory of Chaos event to retrieve.	required
use_cache	bool	If True, use a cached response if available.	True
full	bool	If True, automatically resolve and attach ProcessedEnemy stats to each wave in the stage data. If False, return raw model data.	False

Returns:

Type	Description
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(*, use_cache=True) async

Fetch all Honkai Star Rail monsters.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use the response cache.	True

Returns:

Type	Description
list[Monster]	A list of monster objects.

fetch_monsters_detail(monster_id, *, use_cache=True) async

Fetch the full detail of a specific monster.

Parameters:

Name	Type	Description	Default
monster_id	int	The ID of the monster to retrieve.	required
use_cache	bool	Whether to use the response cache.	True

Returns:

Type	Description
MonsterDetail	A MonsterDetail object containing the full monster stats and metadata.

fetch_new(*, use_cache=True) async

Fetch the ID of beta items in Honkai Star Rail.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use the response cache.	True

Returns:

Type	Description
New	A model representing the new items.

fetch_pf(*, use_cache=True) async

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

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use the response cache.	True

Returns:

Type	Description
list[EndgameSummary]	A list of EndgameSummary objects for each Pure Fiction event.

fetch_pf_detail(pf_id, *, full=False, use_cache=True) async

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

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

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

Parameters:

Name	Type	Description	Default
pf_id	int	The ID of the Pure Fiction event.	required
use_cache	bool	Whether to use the response cache.	True
full	bool	If True, return calculated ProcessedEnemy stats instead of the raw model.	False

Returns:

Type	Description
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(set_id, *, use_cache=True) async

Fetch the details of a Honkai Star Rail relic set.

Parameters:

Name	Type	Description	Default
set_id	int	The relic set ID.	required
use_cache	bool	Whether to use the response cache.	True

Returns:

Type	Description
RelicSetDetail	The relic set details object.

fetch_relic_sets(*, use_cache=True) async

Fetch all Honkai Star Rail relic sets.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use the response cache.	True

Returns:

Type	Description
list[RelicSet]	A list of relic set objects.