# Medium Posts API

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

**Pricing:** $0.002 per post

**Endpoint:** `POST /v1/data/medium/posts/run`

**Auth:** `Authorization: Bearer mk_live_...`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tags` | array | No | 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` | array | No | 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 | No | 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. |
| `publishedAfter` | string | No | 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 | No | Only posts published on or before this date, for example 2025-06-30, or a relative time such as 7 days. |
| `minClaps` | integer | No | Only posts with at least this many claps (Medium's likes), for example 100. 0 by default, which keeps every post. |
| `language` | string | No | Only posts in this language, as a two-letter code, for example en or es. Leave empty for all languages. |
| `maxResults` | integer | No | How many posts to return in total. Defaults to 100; use 0 for all. |

## Example

`?wait=true` holds the request open until the run finishes (up to 60s) and returns the rows inline: one request, no polling.

```bash
curl -X POST "https://api.mindcase.co/v1/data/medium/posts/run?wait=true" \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{}}'
```

```python
import requests

resp = requests.post(
    "https://api.mindcase.co/v1/data/medium/posts/run",
    params={"wait": "true"},
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={"params": {}},
)
rows = resp.json()["data"]
```

## Longer runs

If the run is still going at the 60s ceiling you get back `{ job_id, status: "running" }` instead of rows (same if the result is over 100 rows; those come back `truncated`). Poll with that `job_id`:

```bash
# 1) check status
curl https://api.mindcase.co/v1/jobs/JOB_ID \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"

# 2) when status == completed, fetch the rows
curl https://api.mindcase.co/v1/jobs/JOB_ID/results \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"
```

Full API reference (auth, jobs, balance, SDKs, MCP): https://mindcase.co/skills.md

## Response columns

| Field | Display 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 |