# List Tag Posts

List a bounded public post timeline for a Tumblr tag

- Platform: [Tumblr](https://docs.upscrape.com/docs/platforms/tumblr)
- Capability ID: `tumblr.tag-posts.list`
- Cost: 1 credit per request
- Maximum runtime: 30 seconds
- Execute endpoint: `POST https://data.upscrape.com/execute`

## Request

Use the exact public capability ID in the shared execute envelope.

```bash
curl --request POST \
  --url https://data.upscrape.com/execute \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Prefer: wait=30" \
  --data '{
  "input": {
    "limit": 5,
    "tag": "photography"
  },
  "capability": "tumblr.tag-posts.list"
}'
```

## Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | No | Maximum number of posts to return |
| `tag` | `string` | Yes | Tumblr tag |

### Example input

```json
{
  "limit": 5,
  "tag": "photography"
}
```

## Response

Successful output is returned in `results[0].data`. Raw platform output is intentionally open-ended and may evolve with the upstream source.

### Illustrative sample output

This redacted fixture is an example, not a fixed response schema.

```json
{
  "posts": [
    {
      "blogName": "princesssokphanny",
      "content": [
        {
          "text": "A once-in-a-lifetime shot — the moon perfectly framed by a rainbow. Caught at just the right time. 🌈 🌕",
          "type": "text"
        },
        {
          "media": [
            {
              "hasOriginalDimensions": true,
              "height": 2048,
              "mediaKey": "bd50af3b52c14255a0f7f3a8ca8aec3d:05f26ead8ff3139b-27",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/bd50af3b52c14255a0f7f3a8ca8aec3d/05f26ead8ff3139b-27/s2048x3072/[redacted:token].jpg",
              "width": 1365
            },
            {
              "hasOriginalDimensions": false,
              "height": 1920,
              "mediaKey": "bd50af3b52c14255a0f7f3a8ca8aec3d:05f26ead8ff3139b-27",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/bd50af3b52c14255a0f7f3a8ca8aec3d/05f26ead8ff3139b-27/s1280x1920/[redacted:token].jpg",
              "width": 1280
            },
            {
              "hasOriginalDimensions": false,
              "height": 960,
              "mediaKey": "bd50af3b52c14255a0f7f3a8ca8aec3d:05f26ead8ff3139b-27",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/bd50af3b52c14255a0f7f3a8ca8aec3d/05f26ead8ff3139b-27/s640x960/[redacted:token].jpg",
              "width": 640
            }
          ],
          "type": "image"
        },
        {
          "media": [
            {
              "hasOriginalDimensions": true,
              "height": 2048,
              "mediaKey": "203c9e6234ac4bbfee2f11f4c2d560cb:05f26ead8ff3139b-e3",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/203c9e6234ac4bbfee2f11f4c2d560cb/05f26ead8ff3139b-e3/s2048x3072/[redacted:token].jpg",
              "width": 1365
            },
            {
              "hasOriginalDimensions": false,
              "height": 1920,
              "mediaKey": "203c9e6234ac4bbfee2f11f4c2d560cb:05f26ead8ff3139b-e3",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/203c9e6234ac4bbfee2f11f4c2d560cb/05f26ead8ff3139b-e3/s1280x1920/[redacted:token].jpg",
              "width": 1280
            },
            {
              "hasOriginalDimensions": false,
              "height": 960,
              "mediaKey": "203c9e6234ac4bbfee2f11f4c2d560cb:05f26ead8ff3139b-e3",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/203c9e6234ac4bbfee2f11f4c2d560cb/05f26ead8ff3139b-e3/s640x960/[redacted:token].jpg",
              "width": 640
            }
          ],
          "type": "image"
        }
      ],
      "id": "798772056005148672",
      "noteCount": 192968,
      "postUrl": "https://www.tumblr.com/princesssokphanny/798772056005148672/a-once-in-a-lifetime-shot-the-moon-perfectly",
      "summary": "A once-in-a-lifetime shot — the moon perfectly framed by a rainbow. Caught at just the right time. 🌈 🌕",
      "tags": [
        "aesthetic",
        "sky",
        "skies"
      ],
      "timestamp": 1761768394,
      "type": "blocks"
    },
    {
      "blogName": "maviyenot",
      "content": [
        {
          "media": [
            {
              "hasOriginalDimensions": true,
              "height": 729,
              "mediaKey": "a8cc4be7e9f842edfa3349ce12853008:08b5b035d2eca073-15",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/a8cc4be7e9f842edfa3349ce12853008/08b5b035d2eca073-15/s1280x1920/[redacted:token].jpg",
              "width": 1248
            },
            {
              "hasOriginalDimensions": false,
              "height": 374,
              "mediaKey": "a8cc4be7e9f842edfa3349ce12853008:08b5b035d2eca073-15",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/a8cc4be7e9f842edfa3349ce12853008/08b5b035d2eca073-15/s640x960/[redacted:token].jpg",
              "width": 640
            },
            {
              "hasOriginalDimensions": false,
              "height": 315,
              "mediaKey": "a8cc4be7e9f842edfa3349ce12853008:08b5b035d2eca073-15",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/a8cc4be7e9f842edfa3349ce12853008/08b5b035d2eca073-15/s540x810/[redacted:token].jpg",
              "width": 540
            }
          ],
          "type": "image"
        },
        {
          "media": [
            {
              "hasOriginalDimensions": true,
              "height": 740,
              "mediaKey": "acaccd50cea63cdf2c712695c3171cbb:08b5b035d2eca073-53",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/acaccd50cea63cdf2c712695c3171cbb/08b5b035d2eca073-53/s1280x1920/[redacted:token].jpg",
              "width": 1248
            },
            {
              "hasOriginalDimensions": false,
              "height": 379,
              "mediaKey": "acaccd50cea63cdf2c712695c3171cbb:08b5b035d2eca073-53",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/acaccd50cea63cdf2c712695c3171cbb/08b5b035d2eca073-53/s640x960/[redacted:token].jpg",
              "width": 640
            },
            {
              "hasOriginalDimensions": false,
              "height": 320,
              "mediaKey": "acaccd50cea63cdf2c712695c3171cbb:08b5b035d2eca073-53",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/acaccd50cea63cdf2c712695c3171cbb/08b5b035d2eca073-53/s540x810/[redacted:token].jpg",
              "width": 540
            }
          ],
          "type": "image"
        },
        {
          "media": [
            {
              "hasOriginalDimensions": true,
              "height": 739,
              "mediaKey": "589c662a6fc6a03bb61cf410353707b4:08b5b035d2eca073-d1",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/589c662a6fc6a03bb61cf410353707b4/08b5b035d2eca073-d1/s1280x1920/[redacted:token].jpg",
              "width": 1248
            },
            {
              "hasOriginalDimensions": false,
              "height": 379,
              "mediaKey": "589c662a6fc6a03bb61cf410353707b4:08b5b035d2eca073-d1",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/589c662a6fc6a03bb61cf410353707b4/08b5b035d2eca073-d1/s640x960/[redacted:token].jpg",
              "width": 640
            },
            {
              "hasOriginalDimensions": false,
              "height": 320,
              "mediaKey": "589c662a6fc6a03bb61cf410353707b4:08b5b035d2eca073-d1",
              "type": "image/jpeg",
              "url": "https://64.media.tumblr.com/589c662a6fc6a03bb61cf410353707b4/08b5b035d2eca073-d1/s540x810/[redacted:token].jpg",
              "width": 540
            }
          ],
          "type": "image"
        }
      ],
      "id": "803898915346956288",
      "noteCount": 126343,
      "postUrl": "https://maviyenot.tumblr.com/post/803898915346956288",
      "tags": [
        "maviyenot",
        "photography",
        "artists on tumblr"
      ],
      "timestamp": 1766657748,
      "type": "blocks"
    },
    {
      "blogName": "gentle-cottage",
      "content": [
        {
          "media": [
            {
              "hasOriginalDimensions": true,
              "height": 747,
              "mediaKey": "b9930ee2c1216ef83d80da2f31063996:96d3267595f1875b-f9",
              "type": "image/png",
              "url": "https://64.media.tumblr.com/b9930ee2c1216ef83d80da2f31063996/96d3267595f1875b-f9/s1280x1920/[redacted:token].pnj",
              "width": 736
            },
            {
              "hasOriginalDimensions": false,
              "height": 650,
              "mediaKey": "b9930ee2c1216ef83d80da2f31063996:96d3267595f1875b-f9",
              "type": "image/png",
              "url": "https://64.media.tumblr.com/b9930ee2c1216ef83d80da2f31063996/96d3267595f1875b-f9/s640x960/[redacted:token].pnj",
              "width": 640
            },
            {
              "hasOriginalDimensions": false,
              "height": 548,
              "mediaKey": "b9930ee2c1216ef83d80da2f31063996:96d3267595f1875b-f9",
              "type": "image/png",
              "url": "https://64.media.tumblr.com/b9930ee2c1216ef83d80da2f31063996/96d3267595f1875b-f9/s540x810/[redacted:token].pnj",
              "width": 540
            }
          ],
          "type": "image"
        }
      ],
      "id": "812527574071885824",
      "noteCount": 54571,
      "postUrl": "https://www.tumblr.com/gentle-cottage/812527574071885824",
      "tags": [
        "landsccape",
        "paradise",
        "nature"
      ],
      "timestamp": 1774886678,
      "type": "blocks"
    }
  ],
  "totalCount": 5
}
```
### Illustrative output fields

Derived from the sample above for orientation only. These fields are not a fixed response schema.

| Path | Observed type | Example |
| --- | --- | --- |
| `posts` | `array` | 3 items |
| `posts` | `array` | 3 items |
| `totalCount` | `integer` | 5 |

## Execution behavior

A `200` response completed inline. A `202` response was queued; poll `GET /jobs/{id}` until the job reaches `completed` or `failed`. Use an `Idempotency-Key` when retrying must not create a duplicate logical job.

## Related documentation

- [Authentication](https://docs.upscrape.com/docs/api/authentication)
- [Jobs and results](https://docs.upscrape.com/docs/api/jobs)
- [Errors and retries](https://docs.upscrape.com/docs/api/errors)
- [Idempotency](https://docs.upscrape.com/docs/api/idempotency)