Core Concepts

The SocialKit Go SDK has a deliberately uniform API shape. A typical service method accepts a context.Context and a typed request pointer, then returns a typed result, *ResponseMeta, and error.

result, meta, err := client.YouTube.Stats(ctx, &socialkit.FetchRequest{
    URL: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
})

The only intentional exception is an experimental bulk method, which returns json.RawMessage because SocialKit’s bulk response schemas do not guarantee a stable typed payload. 1 2

The three return values

Value	Meaning	When to use it
result	The JSON data payload decoded into an SDK model.	Read the requested transcript, stats, comments, job, or other domain data.
meta	Metadata collected from the HTTP response.	Inspect status, credit use, rate-limit headers, non-auth headers, or redacted raw response body.
err	A context, transport, decode, or typed API error.	Branch using errors.Is and obtain detailed values with errors.As.

Check err before using result. On a non-2xx API response, meta may still be available because the SDK builds it from headers before constructing the returned error. 3 4

Request types

The SDK uses a compact group of request structs. Fields represented by pointers are optional; leave them nil when you want the upstream default or when a parameter is not relevant to that endpoint. 5

Request type	Required field	Optional fields	Common operations
FetchRequest	URL	Cache, CacheTTL	Transcripts, stats, profiles, individual posts, channel stats.
SummaryRequest	URL	CustomPrompt, CustomResponse, Cache, CacheTTL	Summarization.
CommentsRequest	URL	Limit, Cursor, SortBy, Cache, CacheTTL	Platform comments.
ListRequest	URL	Limit, Cursor, Cache, CacheTTL	Channel feeds, posts, and reels.
SearchRequest	Query	Limit, SortBy, UploadDate, DatePosted, Type, Cache, CacheTTL	YouTube and TikTok search.
VideosRequest	URL	Limit, FullDetails, Cache, CacheTTL	YouTube channel or playlist videos.
ReelsSearchRequest	Query	Limit, Page, Cache, CacheTTL	Instagram reels search.
TweetsRequest	URL	Limit, Cursor, Cache, CacheTTL	X/Twitter tweet listings.
CompanyPostsRequest	URL	Limit, Cache, CacheTTL	LinkedIn company posts.
DownloadRequest	URL	Format, Quality, Country	Synchronous YouTube, TikTok, and Instagram downloads.
V2DownloadRequest	URL	Format, Quality, Country, MaxDuration	Asynchronous v2 downloads.

Optional-value helpers

Use the package helpers to create optional values without temporary variables:

comments, _, err := client.YouTube.Comments(ctx, &socialkit.CommentsRequest{
    URL:    videoURL,
    Limit:  socialkit.IntPtr(50),
    SortBy: socialkit.StringPtr("top"),
    Cache:  socialkit.BoolPtr(true),
})

StringPtr, IntPtr, BoolPtr, and Float64Ptr simply return pointers to their arguments. 6

Response metadata

ResponseMeta lets an integration observe request context without forcing endpoint-specific response models to carry transport details. It includes the HTTP status, a copy of non-sensitive response headers, a redacted raw body, and parsed values from standard credit and rate-limit headers when present. 4 7

ResponseMeta field	Meaning
HTTPStatus	HTTP status code returned by the server.
Headers	Response headers excluding authentication-related headers.
CreditsUsed	Parsed X-Credits-Used, when supplied.
CreditsRemaining	Parsed X-Credits-Remaining, when supplied.
RateLimitLimit	Parsed X-RateLimit-Limit, when supplied.
RateLimitRemaining	Parsed X-RateLimit-Remaining, when supplied.
RateLimitReset	Parsed X-RateLimit-Reset, when supplied.
RetryAfter	Parsed Retry-After, when supplied.
RawBody	Response bytes with credential-like values redacted.

_, meta, err := client.Credits.Get(ctx)
if err != nil {
    return err
}

if meta.CreditsRemaining != nil {
    log.Printf("credits remaining: %.0f", *meta.CreditsRemaining)
}
if meta.RateLimitRemaining != nil {
    log.Printf("rate-limit requests remaining: %d", *meta.RateLimitRemaining)
}

Metadata fields are pointers where the header may be absent. Always nil-check before dereferencing.

Caching parameters

Several request structs expose Cache and CacheTTL. The SDK sends an explicitly set value to SocialKit; it does not independently cache data. SocialKit’s documentation describes server-side caching as an endpoint parameter and treats cache_ttl as a seconds-based TTL. The exact availability and accepted range remain endpoint-level API concerns. 2 5

req := &socialkit.FetchRequest{
    URL:      videoURL,
    Cache:    socialkit.BoolPtr(true),
    CacheTTL: socialkit.IntPtr(3600),
}
transcript, _, err := client.TikTok.Transcript(ctx, req)

Summary extensions and forward compatibility

Summary has first-class fields such as Summary, MainTopics, KeyPoints, Tone, and TargetAudience. It also exposes Extra map[string]json.RawMessage, which preserves unrecognised top-level result fields. This is useful when a CustomResponse requests a response shape that is not otherwise part of the stable model. 5

summary, _, err := client.YouTube.Summarize(ctx, &socialkit.SummaryRequest{
    URL:          videoURL,
    CustomPrompt: socialkit.StringPtr("Focus on technical decisions."),
    CustomResponse: map[string]interface{}{
        "sentiment":  "",
        "keyTakeaway": "",
    },
})
if err != nil {
    return err
}

if raw, ok := summary.Extra["sentiment"]; ok {
    var sentiment string
    if err := json.Unmarshal(raw, &sentiment); err != nil {
        return err
    }
    fmt.Println(sentiment)
}

For certain upstream structures that have no fixed schema, the SDK intentionally uses json.RawMessage or map[string]interface{} rather than inventing a fragile model. Handle those fields as version-tolerant JSON. 2 5

References