InstaloaderContext (Low-level functions)


class instaloader.InstaloaderContext(sleep: bool = True, quiet: bool = False, user_agent: str | None = None, max_connection_attempts: int = 3, request_timeout: float = 300.0, rate_controller: Callable[[InstaloaderContext], RateController] | None = None, fatal_status_codes: List[int] | None = None, iphone_support: bool = True)

Class providing methods for (error) logging and low-level communication with Instagram.

It is not thought to be instantiated directly, rather Instaloader instances maintain a context object.

For logging, it provides log(), error(), error_catcher().

It provides low-level communication routines get_json(), graphql_query(), graphql_node_list(), get_and_write_raw() and implements mechanisms for rate controlling and error handling.

Further, it provides methods for logging in and general session handles, which are used by that routines in class Instaloader.


Print error log and close session


Sleep a short time if self.sleep is set. Called before each request to

error(msg, repeat_at_end=True)

Log a non-fatal error message to stderr, which is repeated at program termination.

  • msg – Message to be printed.

  • repeat_at_end – Set to false if the message should be printed, but not repeated at program termination.

error_catcher(extra_info: str | None = None)

Context manager to catch, print and record InstaloaderExceptions.


extra_info – String to prefix error message with.

get_and_write_raw(url: str, filename: str) None

Downloads and writes anonymously-requested raw data into a file.

get_anonymous_session() Session

Returns our default anonymous requests.Session object.

get_iphone_json(path: str, params: Dict[str, Any]) Dict[str, Any]

JSON request to

  • path – URL, relative to

  • params – GET parameters


Decoded response dictionary


New in version 4.2.1.

get_json(path: str, params: Dict[str, Any], host: str = '', session: Session | None = None, _attempt=1, response_headers: Dict[str, Any] | None = None) Dict[str, Any]

JSON request to Instagram.

  • path – URL, relative to the given domain which defaults to

  • params – GET parameters

  • host – Domain part of the URL from where to download the requested JSON; defaults to

  • session – Session to use, or None to use self.session


Decoded response dictionary

get_raw(url: str, _attempt=1) Response

Downloads a file anonymously.


New in version 4.2.1.

graphql_node_list(query_hash: str, query_variables: Dict[str, Any], query_referer: str | None, edge_extractor: Callable[[Dict[str, Any]], Dict[str, Any]], rhx_gis: str | None = None, first_data: Dict[str, Any] | None = None) Iterator[Dict[str, Any]]

Retrieve a list of GraphQL nodes.

Deprecated since version 4.5: Use NodeIterator instead, which provides more functionality.

graphql_query(query_hash: str, variables: Dict[str, Any], referer: str | None = None, rhx_gis: str | None = None) Dict[str, Any]

Do a GraphQL Query.

  • query_hash – Query identifying hash.

  • variables – Variables for the Query.

  • referer – HTTP Referer, or None.

  • rhx_gis – ‘rhx_gis’ variable as somewhere returned by Instagram, needed to ‘sign’ request


The server’s response dictionary.

property has_stored_errors: bool

Returns whether any error has been reported and stored to be repeated at program termination.

head(url: str, allow_redirects: bool = False) Response

HEAD a URL anonymously.


New in version 4.7.6.

property is_logged_in: bool

True, if this Instaloader instance is logged in.

load_session(username, sessiondata)

Not meant to be used directly, use Instaloader.load_session().

load_session_from_file(username, sessionfile)

Not meant to be used directly, use Instaloader.load_session_from_file().

log(*msg, sep='', end='\n', flush=False)

Log a message to stdout that can be suppressed with –quiet.

login(user, passwd)

Not meant to be used directly, use Instaloader.login().


Changed in version 4.12: Raises LoginException instead of ConnectionException when an error happens. Raises LoginException instead of InvalidArgumentException when the username does not exist.

property root_rhx_gis: str | None

rhx_gis string returned in the / query.


Not meant to be used directly, use Instaloader.save_session().


Not meant to be used directly, use Instaloader.save_session_to_file().

test_login() str | None

Not meant to be used directly, use Instaloader.test_login().


Second step of login if 2FA is enabled. Not meant to be used directly, use Instaloader.two_factor_login().


New in version 4.2.


New in version 4.11.

write_raw(resp: bytes | Response, filename: str) None

Write raw response data into a file.

New in version 4.2.1.


class instaloader.RateController(context: InstaloaderContext)

Class providing request tracking and rate controlling to stay within rate limits.

It can be overridden to change Instaloader’s behavior regarding rate limits, for example to raise a custom exception when the rate limit is hit:

import instaloader

class MyRateController(instaloader.RateController):
    def sleep(self, secs):
        raise MyCustomException()

L = instaloader.Instaloader(rate_controller=lambda ctx: MyRateController(ctx))

New in version 4.5.

count_per_sliding_window(query_type: str) int

Return how many requests of the given type can be done within a sliding window of 11 minutes.

This is called by RateController.query_waittime() and allows to simply customize wait times before queries at query_type granularity. Consider overriding RateController.query_waittime() directly if you need more control.

handle_429(query_type: str) None

This method is called to handle a 429 Too Many Requests response.

It calls RateController.query_waittime() to determine the time needed to wait and then calls RateController.sleep() to wait until we can repeat the same request.

query_waittime(query_type: str, current_time: float, untracked_queries: bool = False) float

Calculate time needed to wait before query can be executed.

sleep(secs: float)

Wait given number of seconds.

wait_before_query(query_type: str) None

This method is called before a query to Instagram.

It calls RateController.query_waittime() to determine the time needed to wait and then calls RateController.sleep() to wait until the request can be made.

Next Section