# GitHub Releases API

GitHub

Returns a public GitHub repository's releases, newest first, from its link or owner/name. Each release has its tag, title, release notes in Markdown, author, pre-release flag and publish date, every file with its size, SHA-256 and exact download count, the source code archives, and its reactions. A repository with no releases returns an empty list. [Overview and pricing](https://socialtap.dev/apis/github/releases/index.md)

GET `/v1/github/releases`

## Example

cURL:

```shell
curl -G 'https://socialtap.dev/v1/github/releases' \
  --data-urlencode 'url=https://github.com/cli/cli' \
  -H "x-api-key: $SOCIALTAP_API_KEY"
```

TypeScript SDK:

```typescript
import { SocialTap } from "socialtap";

const client = new SocialTap(); // apiKey defaults to process.env.SOCIALTAP_API_KEY

const res = await client.github.releases.list({ url: "https://github.com/cli/cli" });
console.log(res.data);
console.log(res.credits.charged, res.meta.request_id);
```

Node.js (fetch):

```javascript
const params = new URLSearchParams({
  url: "https://github.com/cli/cli",
});
const res = await fetch(`https://socialtap.dev/v1/github/releases?${params}`, {
  headers: { "x-api-key": process.env.SOCIALTAP_API_KEY ?? "" },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
const { data, page, meta } = body;
console.log(data, meta.credits_charged);
```

Python (requests):

```python
import os

import requests

res = requests.get(
    "https://socialtap.dev/v1/github/releases",
    params={"url": "https://github.com/cli/cli"},
    headers={"x-api-key": os.environ["SOCIALTAP_API_KEY"]},
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
data, page, meta = body["data"], body["page"], body["meta"]
print(data, meta["credits_charged"])
```

Go (net/http):

```go
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"net/url"
	"os"
)

func main() {
	q := url.Values{}
	q.Set("url", "https://github.com/cli/cli")
	req, err := http.NewRequest("GET", "https://socialtap.dev/v1/github/releases?"+q.Encode(), nil)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("x-api-key", os.Getenv("SOCIALTAP_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	var body struct {
		Data  json.RawMessage `json:"data"`
		Page  json.RawMessage `json:"page"`
		Meta  map[string]any  `json:"meta"`
		Error *struct {
			Code    string `json:"code"`
			Message string `json:"message"`
		} `json:"error"`
	}
	if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
		log.Fatal(err)
	}
	if body.Error != nil {
		log.Fatalf("%s: %s", body.Error.Code, body.Error.Message)
	}
	fmt.Println(string(body.Data), body.Meta["credits_charged"])
}
```

200 OK:

```json
{
  "data": [
    {
      "approximate_fields": [],
      "assets": [
        {
          "metrics": {
            "download_count": 3803
          },
          "name": "gh_2.104.0_checksums.txt",
          "sha256": "180df77fb931591d5d65e33f02a76c9ade314d1c335569af73cc6c8fcb365d2c",
          "size_bytes": 1971,
          "url": "https://github.com/cli/cli/releases/download/v2.104.0/gh_2.104.0_checksums.txt"
        },
        {
          "metrics": {
            "download_count": 28
          },
          "name": "gh_2.104.0_linux_386.deb",
          "sha256": "d3b90c66a71249ef1ff38450d1644708071d091388804411cd45ce66de2c5ed6",
          "size_bytes": 14127242,
          "url": "https://github.com/cli/cli/releases/download/v2.104.0/gh_2.104.0_linux_386.deb"
        },
        {
          "metrics": {
            "download_count": 29
          },
          "name": "gh_2.104.0_linux_386.rpm",
          "sha256": "207f175dcf5318390560fbc0b9e501e81a60d03e93b6e56eed689dec424ce95c",
          "size_bytes": 14631570,
          "url": "https://github.com/cli/cli/releases/download/v2.104.0/gh_2.104.0_linux_386.rpm"
        }
      ],
      "author": {
        "avatar_url": "https://avatars.githubusercontent.com/in/15368?v=4",
        "display_name": null,
        "id": "41898282",
        "is_verified": null,
        "url": "https://github.com/apps/github-actions",
        "username": "github-actions[bot]"
      },
      "id": "443387629",
      "is_prerelease": false,
      "metrics": {
        "download_count": 38707
      },
      "notes": "## Protect private forks when deleting repositories\r\n\r\n`gh repo delete` now warns when deleting a private or internal repository will also delete its forks. The additional confirmation is required even with `--yes`.\r\n\r\nNon-interactive workflows and agents must explicitly accept t…",
      "platform": "github",
      "platform_specific": {
        "github": {
          "created_at": "2026-11-12T18:24:58Z",
          "discussion_url": null,
          "is_immutable": true,
          "mention_count": 7,
          "node_id": "RE_kwDODKw3uc4abY7t",
          "reaction_count": 4,
          "reactions": {
            "confused_count": 0,
            "eyes_count": 0,
            "heart_count": 0,
            "hooray_count": 1,
            "laugh_count": 0,
            "rocket_count": 1,
            "thumbs_down_count": 0,
            "thumbs_up_count": 2
          },
          "target_commitish": "3d5a9e355a837f2f5ee78d7484c118cc1342ad1a",
          "updated_at": "2026-11-12T19:05:11Z"
        }
      },
      "published_at": "2026-11-12T19:03:51Z",
      "tag": "v2.104.0",
      "tarball_url": "https://github.com/cli/cli/archive/refs/tags/v2.104.0.tar.gz",
      "title": "GitHub CLI 2.104.0",
      "unknown_fields": [],
      "url": "https://github.com/cli/cli/releases/tag/v2.104.0",
      "zipball_url": "https://github.com/cli/cli/archive/refs/tags/v2.104.0.zip"
    },
    {
      "approximate_fields": [],
      "assets": [
        {
          "metrics": {
            "download_count": 213936
          },
          "name": "gh_2.103.3_checksums.txt",
          "sha256": "f756e7859d90dbb5e85aae5194206c37da220bec9bac23d3d659078a8e766fdc",
          "size_bytes": 1971,
          "url": "https://github.com/cli/cli/releases/download/v2.103.3/gh_2.103.3_checksums.txt"
        },
        {
          "metrics": {
            "download_count": 527
          },
          "name": "gh_2.103.3_linux_386.deb",
          "sha256": "5b3b310d80e6bdb144d256b4c3794f01eac0cf3f6df44e893e5c85573f1138e5",
          "size_bytes": 14148728,
          "url": "https://github.com/cli/cli/releases/download/v2.103.3/gh_2.103.3_linux_386.deb"
        },
        {
          "metrics": {
            "download_count": 227
          },
          "name": "gh_2.103.3_linux_386.rpm",
          "sha256": "156bc68c9efb10bbb5c0c633174e88d4b69df154a6b5bb7e50cfe766ff094b59",
          "size_bytes": 14670638,
          "url": "https://github.com/cli/cli/releases/download/v2.103.3/gh_2.103.3_linux_386.rpm"
        }
      ],
      "author": {
        "avatar_url": "https://avatars.githubusercontent.com/in/15368?v=4",
        "display_name": null,
        "id": "41898282",
        "is_verified": null,
        "url": "https://github.com/apps/github-actions",
        "username": "github-actions[bot]"
      },
      "id": "424663522",
      "is_prerelease": false,
      "metrics": {
        "download_count": 2500192
      },
      "notes": "## What's Changed\r\n### 🐛 Fixes\r\n\r\n* fix(gh auth status): explain expired expiring tokens with `--no-refresh` by @babakks in [#14815](https://github.com/cli/cli/pull/14815)\r\n\r\n\r\n**Full Changelog**: https://github.com/cli/cli/compare/v2.103.2...v2.103.3",
      "platform": "github",
      "platform_specific": {
        "github": {
          "created_at": "2026-10-26T18:02:47Z",
          "discussion_url": null,
          "is_immutable": true,
          "mention_count": 1,
          "node_id": "RE_kwDODKw3uc4ZT9ni",
          "reaction_count": 45,
          "reactions": {
            "confused_count": 0,
            "eyes_count": 0,
            "heart_count": 8,
            "hooray_count": 0,
            "laugh_count": 8,
            "rocket_count": 15,
            "thumbs_down_count": 0,
            "thumbs_up_count": 14
          },
          "target_commitish": "63837fb778d6a39f02be0ce76ff89f2bc8d74bdc",
          "updated_at": "2026-10-26T19:24:06Z"
        }
      },
      "published_at": "2026-10-26T19:20:08Z",
      "tag": "v2.103.3",
      "tarball_url": "https://github.com/cli/cli/archive/refs/tags/v2.103.3.tar.gz",
      "title": "GitHub CLI 2.103.3",
      "unknown_fields": [],
      "url": "https://github.com/cli/cli/releases/tag/v2.103.3",
      "zipball_url": "https://github.com/cli/cli/archive/refs/tags/v2.103.3.zip"
    },
    {
      "approximate_fields": [],
      "assets": [
        {
          "metrics": {
            "download_count": 50142
          },
          "name": "gh_2.103.2_checksums.txt",
          "sha256": "414d6009dc7f9f936d70831af818d1a32aa0ff07a77646861efd207356a36b2d",
          "size_bytes": 1971,
          "url": "https://github.com/cli/cli/releases/download/v2.103.2/gh_2.103.2_checksums.txt"
        },
        {
          "metrics": {
            "download_count": 134
          },
          "name": "gh_2.103.2_linux_386.deb",
          "sha256": "48e9e71d6f8daa87aef42b3df31d83023ece357cfb5321396c65cce2f56edc38",
          "size_bytes": 14147026,
          "url": "https://github.com/cli/cli/releases/download/v2.103.2/gh_2.103.2_linux_386.deb"
        },
        {
          "metrics": {
            "download_count": 60
          },
          "name": "gh_2.103.2_linux_386.rpm",
          "sha256": "acd73ca5af786cc559a00dc7619cb658b830727d7ad5a055464bd1699a647ecd",
          "size_bytes": 14668588,
          "url": "https://github.com/cli/cli/releases/download/v2.103.2/gh_2.103.2_linux_386.rpm"
        }
      ],
      "author": {
        "avatar_url": "https://avatars.githubusercontent.com/in/15368?v=4",
        "display_name": null,
        "id": "41898282",
        "is_verified": null,
        "url": "https://github.com/apps/github-actions",
        "username": "github-actions[bot]"
      },
      "id": "422277825",
      "is_prerelease": false,
      "metrics": {
        "download_count": 661417
      },
      "notes": "### 🐛 Fixes\r\n\r\n* Allow server to arbitrate which GitHub App installation tokens can attach files by @martinajir in [#14804](https://github.com/cli/cli/pull/14804)\r\n* Defer `--attach` credential checks to the upload endpoint by @BagToad in [#14805](https://github.com/cli/cli/pull/…",
      "platform": "github",
      "platform_specific": {
        "github": {
          "created_at": "2026-10-23T20:08:01Z",
          "discussion_url": null,
          "is_immutable": true,
          "mention_count": 2,
          "node_id": "RE_kwDODKw3uc4ZK3LB",
          "reaction_count": 6,
          "reactions": {
            "confused_count": 0,
            "eyes_count": 0,
            "heart_count": 0,
            "hooray_count": 0,
            "laugh_count": 0,
            "rocket_count": 0,
            "thumbs_down_count": 0,
            "thumbs_up_count": 6
          },
          "target_commitish": "4f2cfe92e3499f8581bf39db77e0a1431fa7b55c",
          "updated_at": "2026-10-23T20:28:28Z"
        }
      },
      "published_at": "2026-10-23T20:24:12Z",
      "tag": "v2.103.2",
      "tarball_url": "https://github.com/cli/cli/archive/refs/tags/v2.103.2.tar.gz",
      "title": "GitHub CLI 2.103.2",
      "unknown_fields": [],
      "url": "https://github.com/cli/cli/releases/tag/v2.103.2",
      "zipball_url": "https://github.com/cli/cli/archive/refs/tags/v2.103.2.zip"
    }
  ],
  "page": {
    "has_more": true,
    "next_cursor": "c1.EXAMPLE_CURSOR",
    "next_cursor_expires_at": "2026-10-26T12:00:00Z",
    "end_reason": null
  },
  "meta": {
    "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
    "platform": "github",
    "source": "api",
    "is_cached": false,
    "credits_charged": 1,
    "latency_ms": 1000,
    "fetched_at": "2026-10-25T12:00:00Z",
    "input": {
      "kind": "repository",
      "id": null,
      "url": "https://github.com/cli/cli"
    },
    "credits_remaining": 9999,
    "client_request_id": null,
    "warnings": []
  }
}
```

Long arrays and strings are shortened for display; real responses are complete.

> [!NOTE]
>
> **Good to know**
>
> - metrics.download_count adds up the downloads of the release's files. GitHub counts no download of the source code archives, so a release with no files has a null count.
> - Releases come newest first in GitHub's own order, where releases of the same day are not always in the order they were published. since and until filter on published_at.
> - Drafts are never listed: GitHub shows them only to people who can push to the repository.
> - If GitHub's API refuses, the list is read from the repository's releases page. Notes and download counts are then null, and assets is empty and listed in unknown_fields.

## Authorizations

`x-api-key`stringheaderrequired

Your API key. [Authentication](https://socialtap.dev/docs/authentication/index.md)

## Query parameters

| Name | Type | Description | Example |
| --- | --- | --- | --- |
| `url` required | `string`<br>max 2,048 chars | The repository: its link (https://github.com/cli/cli, or any page under it such as /releases or a release's own page), owner/name (cli/cli), a clone link ending in .git, or the API's link (api.github.com/repos/cli/cli, or api.github.com/repositories/212613049 by the repository's ID). Owner and name are case-insensitive; a renamed or moved repository is followed to its new name. | `https://github.com/cli/cli` |
| `since` optional | `string`<br>date-time | Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. | `2026-10-01` |
| `until` optional | `string`<br>date-time | Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). | `2026-10-08` |
| `limit` optional | `integer`<br>min 1<br>max 10 | Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for. | `10` |
| `cursor` optional | `string` | page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page. | — |

`url` takes GitHub repository links; another kind of link, or another platform's, fails free with [`invalid_input`](https://socialtap.dev/docs/errors/index.md#invalid_input). Unknown parameters are rejected with a suggestion, never ignored ([Requests](https://socialtap.dev/docs/requests/index.md)). `limit` and `cursor` page through the list: see Pagination.

**Parameters every endpoint accepts**

| Name | Type | Description | Example |
| --- | --- | --- | --- |
| `max_age` optional | `integer`<br>min 0 | Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent. | — |
| `fields` optional | `string` | Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments\[\].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole. | — |

## Response

### 200

`{data, page, meta}`. `data` is an array of up to 10 [release](https://socialtap.dev/resources/release/index.md) objects, Newest first, as GitHub orders them: releases of the same day are not always in the order they were published; `page` says how to get the next page; `meta` describes the request ([meta](https://socialtap.dev/docs/reference/index.md#meta)). Fields only GitHub has are under `platform_specific.github`.

| Field | Type | Description |
| --- | --- | --- |
| `data[].platform` | `string` | Platform ID (github, …). |
| `data[].id` | `string` | Platform-native release ID (string): the platform's own where it has one, else derived from its repository or package and its tag, stable for the release's life. |
| `data[].url` | `string` (uri) | Canonical release page URL. |
| `data[].tag` | `string` | The tag the release is cut from, as written (v19.3.1, react-dom@19.0.0); on a package registry, the version (2.32.3). |
| `data[].title` | `string` or `null` | The release's title as its author wrote it; null when it has none (the platform's page then shows the tag). |
| `data[].notes` | `string` or `null` | Release notes as the author wrote them, in Markdown (the platform's own flavor: links, headings, @mentions); null when the release has none. |
| `data[].author` | `object` or `null` | The account that published the release (often a bot on automated releases); null when the platform does not name one. |
| `data[].author.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `data[].author.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `data[].author.display_name` | `string` or `null` | Display name shown on the profile. |
| `data[].author.url` | `string` (uri) or `null` | Canonical profile URL. |
| `data[].author.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `data[].author.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `data[].is_prerelease` | `boolean` or `null` | Marked by its author as a pre-release (beta, release candidate), not ready for production; null when the platform has no such mark. |
| `data[].published_at` | `string` (date-time) or `null` | When the release was published, RFC 3339 UTC; on GitLab it can be a future date (an upcoming release). Null when the platform does not show it. |
| `data[].assets` | `object[]` | Files published with the release, in the platform's order; \[\] when none (listed in unknown_fields when the source cannot see them). |
| `data[].assets[].name` | `string` | The file's name, or on platforms whose assets are links (GitLab) the link's label. |
| `data[].assets[].url` | `string` (uri) | Where the file downloads from (a permanent link; it may redirect to a CDN). |
| `data[].assets[].size_bytes` | `integer` or `null` | File size in bytes; null when the platform does not state it (GitLab's links). |
| `data[].assets[].sha256` | `string` or `null` | SHA-256 digest of the file, 64 lowercase hex characters; null when the platform does not publish one. |
| `data[].assets[].metrics` | `object` | Counts at fetch time; null = not exposed, 0 = zero. |
| `data[].assets[].metrics.download_count` | `integer` or `null` | Times the file was downloaded; null when the platform does not count them. |
| `data[].tarball_url` | `string` (uri) or `null` | The source code at the release's tag as a .tar.gz archive, built by the platform; null when it serves none (a package registry, a repository that hides archives). |
| `data[].zipball_url` | `string` (uri) or `null` | The source code at the release's tag as a .zip archive, built by the platform; null when it serves none. |
| `data[].metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `data[].metrics.download_count` | `integer` or `null` | Downloads of the release's files: the sum of its assets' download counts. Source archives are not counted. Null when no asset's downloads are counted (a release with no files, a platform that counts none). |
| `data[].platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `data[].platform_specific.github` | `object` or `null` | A GitHub release's own fields. |
| `data[].platform_specific.github.node_id` | `string` or `null` | GitHub's GraphQL node ID of the release (RE_kwDO…). |
| `data[].platform_specific.github.target_commitish` | `string` or `null` | The branch or commit the release's tag was created from (main, or a commit SHA), as its author chose it. |
| `data[].platform_specific.github.created_at` | `string` (date-time) or `null` | The date of the commit the release was created from, RFC 3339 UTC; published_at is when the release itself came out. |
| `data[].platform_specific.github.updated_at` | `string` (date-time) or `null` | When the release was last edited (its notes or files), RFC 3339 UTC. |
| `data[].platform_specific.github.is_immutable` | `boolean` or `null` | True when the release is immutable: its tag and files can no longer be changed or replaced. |
| `data[].platform_specific.github.discussion_url` | `string` (uri) or `null` | The discussion thread opened for the release; null when it has none. |
| `data[].platform_specific.github.mention_count` | `integer` or `null` | Accounts the release notes mention (GitHub's list of contributors under the release), 0 when they mention nobody; null when the source does not show them. |
| `data[].platform_specific.github.reaction_count` | `integer` or `null` | Reactions to the release, all emoji together, 0 when nobody reacted; null when the source does not show them. |
| `data[].platform_specific.github.reactions` | `object` | Reactions to the release by emoji, 0 for an emoji nobody used; each null when the source does not show them. |
| `data[].platform_specific.github.reactions.thumbs_up_count` | `integer` or `null` | 👍 (+1) reactions; metrics.like_count. |
| `data[].platform_specific.github.reactions.thumbs_down_count` | `integer` or `null` | 👎 (-1) reactions. |
| `data[].platform_specific.github.reactions.laugh_count` | `integer` or `null` | 😄 reactions. |
| `data[].platform_specific.github.reactions.hooray_count` | `integer` or `null` | 🎉 reactions. |
| `data[].platform_specific.github.reactions.confused_count` | `integer` or `null` | 😕 reactions. |
| `data[].platform_specific.github.reactions.heart_count` | `integer` or `null` | ❤️ reactions. |
| `data[].platform_specific.github.reactions.rocket_count` | `integer` or `null` | 🚀 reactions. |
| `data[].platform_specific.github.reactions.eyes_count` | `integer` or `null` | 👀 reactions. |
| `data[].approximate_fields` | `string[]` | JSON paths of values rounded by the platform or parsed from display text. \[\] when all exact. |
| `data[].unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none (a source that cannot see a release's assets); null already means unknown for every other field. \[\] when every list is known. |

not_found and private_or_unavailable are item-level: the request was fine, the item can't be returned.

### 400

400 Bad Request: 2 error codes. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `invalid_input` | 400 | No | A parameter is missing or malformed, or the link is not one this endpoint takes. | Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one. |
| `invalid_cursor` | 400 | No | The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. | Repeat the original request without cursor to start the list again. |

### 401

401 Unauthorized: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `unauthorized` | 401 | No | The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. | Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url. |

### 402

402 Payment Required: 2 error codes. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `insufficient_credits` | 402 | No | The account does not have enough credits for this request. | Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically. |
| `spend_limit_reached` | 402 | No | The API key reached its spend limit for this period. The account may still have credits. | Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically. |

### 403

403 Forbidden: 2 error codes. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `forbidden` | 403 | No | The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. | Act on details.reason. suspended: contact [support](mailto:support@socialtap.dev). scope: use a key with details.required_scope. previous_secret: use the new secret. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP. |
| `private_or_unavailable` | 403 | No | The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. | Only public items can be fetched. Do not retry. |

### 404

404 Not Found: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `not_found` | 404 | No | The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). | Check the link or ID. Do not retry. |

### 429

429 Too Many Requests: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `rate_limited` | 429 | Yes, later | The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. | Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask [support](mailto:support@socialtap.dev) to raise the ceiling; without an API key, send one. |

### 451

451: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `unavailable_for_legal_reasons` | 451 | No | We removed this item after a copyright notice or another legal request, so we don't return it. The request was free. A list leaves such items out instead, with an items_omitted warning. | Do not retry. The item stays unavailable unless the notice is withdrawn. |

### 500

500 Internal Error: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `internal` | 500 | Yes, later | An unexpected error on SocialTap's side. | Retry with backoff. If it keeps happening, contact [support](mailto:support@socialtap.dev) with the request_id. |

### 502

502 Bad Gateway: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `upstream_error` | 502 | Yes, later | The platform failed, or answered with something we could not read. | Retry with backoff. Failed requests are free. |

### 503

503 Unavailable: 2 error codes. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `upstream_blocked` | 503 | Yes, later | The platform refused every attempt, our own retries included. | Retry later with backoff. Failed requests are free. |
| `overloaded` | 503 | Yes, later | SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. | Retry after the seconds in the retry-after header. Failed requests are free. |

## Pagination

Items come in pages, **newest first, as GitHub orders them: releases of the same day are not always in the order they were published**. To get the next page, send **the same request plus `cursor`** set to `page.next_cursor` from the previous response. Keep every other parameter the same (limit, max_age and fields may change); anything else that differs is rejected. When `page.has_more` is `false` the walk is over, and `page.end_reason` says why: only `end` means you have every item (the others say the platform or a page cap stopped the walk early).

- **Order**: Newest first, as GitHub orders them: releases of the same day are not always in the order they were published
- **Page size**: Up to 10 releases (the default; `limit` lowers it)
- **Cursor lifetime**: 24 hours; don't store cursors
- **Price**: Per page, 1 credit

### The `page` object

| Field | Type | Description |
| --- | --- | --- |
| `page.has_more` | `boolean` | True when another page exists; then next_cursor is set. An empty page with has_more true is not the end. |
| `page.next_cursor` | `string` or `null` | Pass as cursor, with the same other parameters, to get the next page; null at the end. |
| `page.next_cursor_expires_at` | `string` (date-time) or `null` | When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors. |
| `page.end_reason` | `string` or `null` | Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.<br>One of `end`, `platform_limit`, `max_pages` |

### Next page

cURL: next page:

```shell
curl -G 'https://socialtap.dev/v1/github/releases' \
  --data-urlencode 'url=https://github.com/cli/cli' \
  --data-urlencode 'cursor=c1.EXAMPLE_CURSOR' \
  -H "x-api-key: $SOCIALTAP_API_KEY"
```

- The price is per page: each successful page costs the same, whatever `limit` is and however many items it has. Empty pages are charged too (an empty page with `has_more: true` is not the end).
- A `limit` below 10 doesn't save credits: the next request serves the rest of the same platform page, which is fetched again and charged as a page each time, and items can shift between those requests if the platform changes the list. Omitting `limit` is the cheapest way to walk the list.
- Errors are free, including a rejected cursor.
- Pages served from the cache are free.
- An expired or altered cursor, or one sent with different parameters, fails with [`invalid_cursor`](https://socialtap.dev/docs/errors/index.md#invalid_cursor) (HTTP 400): Repeat the original request without cursor to start the list again.

[Pagination guide](https://socialtap.dev/docs/pagination/index.md)

## Pricing

From **1 credit** per page. Charged per successful page, whatever its number of items. Errors are free. The price depends on the source that produced the result, reported as `meta.source`; sources are tried cheapest first: Platform API → Public page.

| Source | Price per successful page | Per 1,000 pages |
| --- | --- | --- |
| Platform API `api` | 1 credit | $0.75–$1.97 |
| Public page `page` | 1 credit | $0.75–$1.97 |

**Balance, sources and what you were charged**

Your balance must be at least **1 credit** to start a request; with less, it is refused with [`insufficient_credits`](https://socialtap.dev/docs/errors/index.md#insufficient_credits) (HTTP 402) and costs nothing. Only that minimum is set aside when the request starts.

| meta.source | Source | What it means |
| --- | --- | --- |
| `api` | Platform API | The platform's public, logged-out API. |
| `page` | Public page | Data embedded in the platform's public web page. |

`meta.credits_charged` and the `x-credits-charged` header show what you paid. [How credits work](https://socialtap.dev/docs/credits/index.md) · [Packs](https://socialtap.dev/pricing/index.md)

Endpoint ID `github.releases` · operationId `github.releases.list` · [Product overview](https://socialtap.dev/apis/github/releases/index.md)

---

[HTML version](https://socialtap.dev/docs/reference/github/releases/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)
