instagram

README

instagram

A pure-Go, dependency-free, best-effort read client for public Instagram content served through Instagram's web JSON endpoints.

• CGO-free (CGO_ENABLED=0), Go 1.26.4 floor.
• Zero third-party dependencies — standard library only.
• Small, stable Go API that hides an inherently unstable transport.

⚠️ Fragility & Terms-of-Service caveat

This library is fragile by nature. Read this before depending on it.

Instagram does not offer these endpoints as a stable, documented public API. They are the internal endpoints its own website calls, and they change, rate-limit, and lock without notice. In practice this means:

• Unauthenticated requests are frequently rejected. You will often need a valid logged-in sessionid cookie (see WithSessionID) for reads to succeed.
• Any request can start returning 401 / 403 / 429 at any time when Instagram decides to block you. This library surfaces those as clear errors that mention the status — they indicate blocking/fragility, not a bug in the code.
• The response shape can change at any time, which will surface as decode errors.
• Automated scraping of Instagram may violate Instagram's Terms of Service and/or local law. You are responsible for how you use this library. Use it only for content and in ways you are authorized to access.

The Go API is kept deliberately small and stable so your code can survive the churn underneath. The underlying transport may break at any time regardless.

Install

go get github.com/go-instagram/instagram

Usage

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/go-instagram/instagram"
)

func main() {
	// A sessionid cookie is usually required for reads to succeed.
	c := instagram.New(
		instagram.WithSessionID("your-sessionid-cookie"),
	)

	prof, err := c.UserProfile(context.Background(), "instagram")
	if err != nil {
		log.Fatal(err) // 401/403/429 here means Instagram is blocking the request.
	}

	fmt.Printf("%s (%s) — %d followers\n", prof.FullName, prof.Username, prof.Followers)
	for _, p := range prof.Posts {
		fmt.Printf("- %s  %d likes  %s\n", p.Permalink, p.Likes, p.Caption)
	}
}

Options

Option	Purpose
WithHTTPClient(*http.Client)	Custom HTTP client (timeouts, proxy, transport).
WithBaseURL(string)	Override the request origin (defaults to https://www.instagram.com).
WithUserAgent(string)	Set the User-Agent header.
WithSessionID(string)	Send a sessionid cookie for authenticated reads.

License

BSD-3-Clause. See LICENSE. Copyright the go-instagram/instagram authors.

Documentation

Overview

Package instagram is a pure-Go, dependency-free, best-effort read client for public Instagram content served through Instagram's web JSON endpoints.

This client is fragile BY NATURE. Instagram does not offer these endpoints as a stable public API: it changes, rate-limits, and locks them frequently, and it may reject unauthenticated requests outright. Reads therefore often require a valid logged-in "sessionid" cookie (see WithSessionID), and any request may break at any time when Instagram changes its endpoints, headers, response shape, or blocking policy. Treat non-2xx responses (particularly 401, 403 and 429) as signals that Instagram is blocking the request rather than as a bug in this library.

The package deliberately hides this fragility behind a small, stable Go API so that callers can depend on the types even as the underlying transport shifts.

It uses only the Go standard library and builds with CGO disabled.

Index

• Constants
• type Client
  • func New(opts ...Option) *Client
  • func (c *Client) CurrentUserID(ctx context.Context) (string, error)
  • func (c *Client) Following(ctx context.Context, userID, maxID string) (*FollowingPage, error)
  • func (c *Client) UserProfile(ctx context.Context, username string) (*Profile, error)
• type FollowedUser
• type FollowingPage
• type Option
  • func WithBaseURL(u string) Option
  • func WithCSRFToken(token string) Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithSessionID(sessionID string) Option
  • func WithUserAgent(ua string) Option
• type Post
• type Profile

Constants

const DefaultAppID = "936619743392459"

DefaultAppID is the public web app id Instagram's own site sends as the x-ig-app-id header. It is required by the web_profile_info endpoint.

const DefaultBaseURL = "https://www.instagram.com"

DefaultBaseURL is the default Instagram web origin.

const DefaultUserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) " +
	"AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"

DefaultUserAgent is a browser-like User-Agent used when none is configured.

Types

type Client

type Client struct {
	// BaseURL is the origin requests are sent to. Defaults to DefaultBaseURL.
	BaseURL string
	// HTTPClient performs requests. Defaults to http.DefaultClient.
	HTTPClient *http.Client
	// UserAgent is sent as the User-Agent header.
	UserAgent string
	// SessionID, when set, is sent as the "sessionid" cookie to authenticate
	// reads. Instagram frequently requires this for public data.
	SessionID string
	// CSRFToken, when set, is sent as the "csrftoken" cookie and the X-CSRFToken
	// header. The private friendships endpoints (see [Client.Following]) require
	// it in addition to the sessionid.
	CSRFToken string
	// AppID is sent as the x-ig-app-id header. Defaults to DefaultAppID.
	AppID string
}

Client is a best-effort Instagram web read client. Construct it with New.

func New

func New(opts ...Option) *Client

New builds a Client with sane defaults, then applies the given options.

func (*Client) CurrentUserID

func (c *Client) CurrentUserID(ctx context.Context) (string, error)

CurrentUserID returns the logged-in user's numeric id, read from the private /api/v1/accounts/current_user/ endpoint. It requires a valid sessionid (see WithSessionID); without one Instagram answers 302→login or 4xx, surfaced as an error. The returned id is what Client.Following needs as its userID.

func (*Client) Following

func (c *Client) Following(ctx context.Context, userID, maxID string) (*FollowingPage, error)

Following returns one page of the accounts userID follows, starting at maxID ("" for the first page). It requests GET {BaseURL}/api/v1/friendships/<userID>/following/ with the x-ig-app-id header and the sessionid (and, when configured, csrftoken) cookie — the same authentication the private web app sends. Page through the whole list by passing the previous page's NextMaxID until it comes back "".

This endpoint is private and Instagram gates it aggressively: without a valid sessionid it answers 302→login or 401/403/429, all surfaced here as errors.

func (*Client) UserProfile

func (c *Client) UserProfile(ctx context.Context, username string) (*Profile, error)

UserProfile fetches a public profile and its recent posts.

It requests GET {BaseURL}/api/v1/users/web_profile_info/?username=<u> with the x-ig-app-id header (and the sessionid cookie when configured). This endpoint is undocumented and may require authentication; see the package documentation for the fragility caveats.

type FollowedUser

type FollowedUser struct {
	PK       string // the account's numeric id (as a string)
	Username string // the @handle, without the "@"
	FullName string // the display name ("" when the account sets none)
}

FollowedUser is one account the logged-in user follows, as returned by the friendships following list.

type FollowingPage

type FollowingPage struct {
	Users     []FollowedUser
	NextMaxID string
}

FollowingPage is one page of the logged-in user's following list. NextMaxID is the cursor for the following page, and is "" when there are no more pages.

type Option

type Option func(*Client)

Option configures a Client.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the request origin (useful for testing).

func WithCSRFToken

func WithCSRFToken(token string) Option

WithCSRFToken sets the "csrftoken" cookie / X-CSRFToken header sent with requests to the private friendships endpoints (see Client.Following).

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient sets the http.Client used for requests.

func WithSessionID

func WithSessionID(sessionID string) Option

WithSessionID sets the "sessionid" cookie sent with requests.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header.

type Post

type Post struct {
	ID         string
	Shortcode  string
	Caption    string
	Owner      string // username
	Permalink  string // https://www.instagram.com/p/<shortcode>/
	DisplayURL string // main image
	IsVideo    bool
	VideoURL   string
	Likes      int
	Comments   int
	Timestamp  time.Time
}

Post is a single piece of timeline media on a profile.

type Profile

type Profile struct {
	Username  string
	FullName  string
	Biography string
	Followers int
	Posts     []Post
}

Profile is a public profile and its recent posts.