A lightweight R client for the Substack API. All functions return data frames, handle errors with informative messages, and work out of the box once you’ve set your API key.

Installation

From CRAN:

install.packages("substackR")

Development version from GitHub:

# install.packages("pak")   # if needed
pak::pak("posocap/substackR")

Authentication

Provide your API key once per session with:

library(substackR)
set_substack_key("your-substack-api-key")

If you haven’t set the key, any API call will prompt you to call set_substack_key() first.

Main Functions

get_substack_latest()

Fetches the latest posts.

latest_posts <- get_substack_latest(
  publication_url = "posocap.substack.com",
  limit           = 10,
  offset          = 0
)

Returns a data frame with columns:

slug
url
title
description
excerpt
body_html
reading_time_minutes
audio_url
date
likes
paywall
cover_image
cover_image_color_palette
author
author_image

get_substack_top()

Fetches the top (most liked) posts.

top_posts <- get_substack_top("posocap.substack.com", limit = 5)

get_substack_search()

Searches posts by keyword.

search_results <- get_substack_search(
  publication_url = "posocap.substack.com",
  query           = "data science",
  limit           = 20
)

get_substack_post()

Retrieves a single post by slug.

single_post <- get_substack_post(
  publication_url = "posocap.substack.com",
  slug            = "your-post-slug"
)

Error Handling

Missing API key → error asking you to run set_substack_key().
HTTP errors (4xx, 5xx, rate limits) → cli::cli_abort() with status code and message.
JSON parsing issues → warning + empty data frame.

Contributing

Fork the repo
Create a branch (e.g. feature/xyz)

Install dependencies:

devtools::install_deps(dependencies = TRUE)

Run tests:
```
devtools::test()
```
Submit a pull request.