Models

All API responses are typed Pydantic v2 models. Import them directly:

from funstat_api import UserStats, GroupMember, ChatInfo  # etc.

---

Response wrappers

Every method returns a response wrapper with a consistent shape:

Field	Type	Description
success	bool	Whether the request succeeded
tech	TechInfo	Request cost and balance info
data	... \| None	The actual payload
paging	Paging\| None	Pagination info (paginated endpoints only)

---

TechInfo

class TechInfo:
    request_cost: float
    current_ballance: float
    request_duration: str

---

Paging

class Paging:
    total: int
    current_page: int
    page_size: int
    total_pages: int

---

ResolvedUser

class ResolvedUser:
    id: int
    username: str | None
    first_name: str | None
    last_name: str | None
    is_active: bool
    is_bot: bool
    has_premium: bool | None

---

UserStatsMin

class UserStatsMin:
    id: int
    first_name: str | None
    last_name: str | None
    is_bot: bool
    is_active: bool
    first_msg_date: str | None
    last_msg_date: str | None
    total_msg_count: int
    msg_in_groups_count: int
    adm_in_groups: int
    usernames_count: int
    names_count: int
    total_groups: int

---

UserStats

Extends UserStatsMin with additional fields:

class UserStats(UserStatsMin):
    is_cyrillic_primary: bool | None
    lang_code: str | None
    unique_percent: float | None
    circle_count: int
    voice_count: int
    reply_percent: float
    media_percent: float
    link_percent: float
    favorite_chat: ChatInfo | None
    media_usage: str | None
    stars_val: int | None
    gift_count: int | None
    about: str | None
    # ... and more

---

ChatInfo

class ChatInfo:
    id: int
    title: str
    is_private: bool
    username: str | None

---

ChatInfoExt

Extends ChatInfo:

class ChatInfoExt(ChatInfo):
    is_channel: bool
    link: str | None

---

GroupMember

class GroupMember:
    id: int
    username: str | None
    name: str | None
    first_name: str | None
    last_name: str | None
    is_admin: bool | None
    is_active: bool
    today_msg: int
    has_prem: bool | None
    has_photo: bool
    dc_id: int | None

---

UserMsg

class UserMsg:
    date: str
    message_id: int
    reply_to_message_id: int | None
    media_code: int | None
    media_name: str | None
    text: str | None
    group: ChatInfo

---

UserNameInfo

class UserNameInfo:
    name: str
    date_time: str

---

UsrChatInfo

class UsrChatInfo:
    chat: ChatInfo
    last_message_id: int
    messages_count: int
    last_message: str | None
    first_message: str | None
    is_admin: bool
    is_left: bool

---

GiftRelationInfo

class GiftRelationInfo:
    last_gift_date: str | None
    from_user_id: int
    from_first_name: str | None
    from_last_name: str | None
    from_main_username: str | None
    from_is_active: bool
    to_user_id: int
    to_first_name: str | None
    to_last_name: str | None
    to_main_username: str | None
    to_is_active: bool

---

StickerInfo

class StickerInfo:
    sticker_set_id: int
    last_seen: str
    min_seen: str
    resolved: str | None
    title: str | None
    short_name: str | None
    stickers_count: int | None

---

UCommonGroupInfo

class UCommonGroupInfo:
    user_id: int
    common_groups: int
    first_name: str | None
    last_name: str | None
    username: str | None
    is_user_active: bool

---

UsernameUsageModel

class UsernameUsageModel:
    actual_users: list[ResolvedUser] | None
    usage_by_users_in_the_past: list[ResolvedUser] | None
    actual_groups_or_channels: list[ChatInfoExt] | None
    mention_by_channel_or_group_desc: list[ChatInfoExt] | None

---

WhoWroteText

class WhoWroteText:
    message_id: int
    user_id: int
    date: str
    name: str | None
    username: str | None
    is_active: bool
    group: ChatInfoExt
    text: str | None

---

WhoWroteTextPaged

class WhoWroteTextPaged:
    total: int
    data: list[WhoWroteText]
    is_last_page: bool | None
    page_size: int | None
    current_page: int | None
    total_pages: int | None

---

PingResult

class PingResult:
    request_ping: str     # duration reported by the API
    responce_ping: float  # actual round-trip in seconds

---

Response wrappers reference

Class	.data type
ResolvedUserResponse	list[ResolvedUser]
UserStatsMinResponse	UserStatsMin
UserStatsResponse	UserStats
UserMsgPagedResponse	list[UserMsg]
UserNameInfoResponse	list[UserNameInfo]
UsrChatInfoResponse	list[UsrChatInfo]
GroupMemberResponse	list[GroupMember]
GiftRelationResponse	list[GiftRelationInfo]
StickerInfoResponse	list[StickerInfo]
UCommonGroupInfoResponse	list[UCommonGroupInfo]
UsernameUsageResponse	UsernameUsageModel
ChatInfoExtResponse	list[ChatInfoExt]
WhoWroteTextResponse	WhoWroteTextPaged

---

ResolvedUserResponse

success · TechInfo · data: list[ResolvedUser]

UserStatsMinResponse

success · TechInfo · data: UserStatsMin

UserStatsResponse

success · TechInfo · data: UserStats

UserMsgPagedResponse

success · TechInfo · Paging · data: list[UserMsg]

UserNameInfoResponse

success · TechInfo · data: list[UserNameInfo]

UsrChatInfoResponse

success · TechInfo · data: list[UsrChatInfo]

GroupMemberResponse

success · TechInfo · data: list[GroupMember]

GiftRelationResponse

success · TechInfo · data: list[GiftRelationInfo]

StickerInfoResponse

success · TechInfo · data: list[StickerInfo]

UCommonGroupInfoResponse

success · TechInfo · data: list[UCommonGroupInfo]

UsernameUsageResponse

success · TechInfo · data: UsernameUsageModel

ChatInfoExtResponse

success · TechInfo · data: list[ChatInfoExt]

WhoWroteTextResponse

success · TechInfo · data: WhoWroteTextPaged