> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindcase.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Medium Posts API

> Medium posts with title, subtitle, URL and author details. Search by tag or keyword.

`POST /v1/data/medium/posts/run`

**Pricing:** $0.002 per post ($2.00 per 1,000).

## Ways to call it

* **Keyword search**: set `queries` (optional: `language`, `minClaps`, `publishedAfter`, `publishedBefore`, `maxResults`)
* **By tag**: set `tags` (optional: `tagSort`, `language`, `minClaps`, `publishedAfter`, `publishedBefore`, `maxResults`)

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**tags** `string[]`

Medium topic tags: the labels writers put on their posts, which are open-ended, so any tag that exists on Medium works. A tag is the part after medium.com/tag/, for example artificial-intelligence or startup. You can also type the words ('Data Science') or paste the tag link (medium.com/tag/data-science); both become the tag. Popular tags: artificial-intelligence, programming, startup, marketing, data-science, productivity, crypto, design. A tag that does not exist on Medium returns an error; use Keyword search for free words.

**queries** `string[]`

Words to search Medium posts for, like a search box, for example retrieval augmented generation or remote work. One request reads them all.

**tagSort** `string` (default: newest)

Which list of the tag's posts to read, for example newest or top-month. Newest first by default, the only order that reaches the whole archive; the top and trending lists hold about 100 posts each.

Allowed values: `newest` (Newest first (whole archive)), `trending` (Trending now (about 100 posts)), `top-week` (Top this week (about 100 posts)), `top-month` (Top this month (about 100 posts)), `top-year` (Top this year (about 100 posts)), `top-all-time` (Top of all time (about 100 posts)), `all-top` (Best of every top list (about 400 posts)).

**publishedAfter** `string`

Only posts published on or after this date, for example 2025-01-01, or a relative time such as 30 days or 6 months.

**publishedBefore** `string`

Only posts published on or before this date, for example 2025-06-30, or a relative time such as 7 days.

**minClaps** `integer` (default: 0)

Only posts with at least this many claps (Medium's likes), for example 100. 0 by default, which keeps every post.

Min `0`; max `100000000`.

**language** `string`

Only posts in this language, as a two-letter code, for example en or es. Leave empty for all languages.

**maxResults** `integer` (default: 100)

How many posts to return in total. Defaults to 100; use 0 for all.

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/medium/posts/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "queries": [
      "retrieval augmented generation"
    ],
    "maxResults": 10
  }
}'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.mindcase.co/v1/data/medium/posts/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "queries": [
        "retrieval augmented generation"
    ],
    "maxResults": 10
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/medium/posts/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "queries": [
    "retrieval augmented generation"
  ],
  "maxResults": 10
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one post, keyed by these fields.

| Field | Name | Type |
| - | - | - |
| `postId` | Post ID | text |
| `postUrl` | Post URL | url |
| `title` | Title | text |
| `subtitle` | Subtitle | text |
| `authorName` | Author Name | text |
| `authorHandle` | Author Handle | text |
| `authorUrl` | Author URL | url |
| `authorProfileId` | Author Profile ID | text |
| `authorFollowers` | Author Followers | number |
| `claps` | Claps | number |
| `clappers` | Clappers | number |
| `responses` | Responses | number |
| `readingTimeMinutes` | Reading Time Minutes | number |
| `wordCount` | Word Count | number |
| `postedDate` | Posted Date | text |
| `updatedDate` | Updated Date | text |
| `tags` | Tags | array |
| `language` | Language | text |
| `memberOnly` | Member Only | boolean |
| `publicationName` | Publication Name | text |
| `publicationUrl` | Publication URL | url |
| `publicationFollowers` | Publication Followers | number |
| `previewImage` | Preview Image | image |
| `matchedInput` | Matched Input | text |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "medium/posts",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "publicationName": null,
      "clappers": 0,
      "claps": 0,
      "memberOnly": false,
      "wordCount": 3444,
      "responses": 0,
      "subtitle": "Redes sociales, socialización y bienestar en los adultos mayores",
      "language": "es",
      "authorHandle": "rebecavelasco29",
      "postedDate": "2026-10-31T01:00:08.708Z",
      "authorName": "Rebeca Velasco",
      "updatedDate": "2026-10-31T01:00:08.708Z",
      "previewImage": "https://miro.medium.com/v2/resize:fit:1200/1*cnSOHoH7bymPelVSQAlgEw.jpeg",
      "publicationFollowers": null,
      "postUrl": "https://medium.com/@rebecavelasco29/conectados-pero-acompa%C3%B1ados-bb2ace380d37",
      "readingTimeMinutes": 13.9,
      "authorFollowers": 0,
      "tags": [
        "adultos-mayores",
        "digital-inclusion"
      ],
      "authorUrl": "https://medium.com/@rebecavelasco29",
      "authorProfileId": "023b97c53dde",
      "title": "Conectados, pero.. ¿acompañados?",
      "postId": "bb2ace380d37",
      "publicationUrl": null,
      "matchedInput": "tag:tecnologia"
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.