README
¶
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
sessionidcookie (seeWithSessionID) 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 ¶
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.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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
// 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 (*Client) UserProfile ¶
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 Option ¶
type Option func(*Client)
Option configures a Client.
func WithBaseURL ¶
WithBaseURL overrides the request origin (useful for testing).
func WithHTTPClient ¶
WithHTTPClient sets the http.Client used for requests.
func WithSessionID ¶
WithSessionID sets the "sessionid" cookie sent with requests.
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.
Source Files