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

# Retrieve Tag

> Retrieve a specific blog post tag by slug with tag details and optional recent posts integration.

Retrieve a specific blog post tag by its unique slug identifier, providing detailed tag information and optional recent posts integration. Tags provide granular categorization and labeling for blog content, enabling detailed content organization and enhanced discovery capabilities.

**Tag Information**: The tag object contains the display name (e.g., "API Development") and URL-friendly slug identifier (e.g., "api-development") that can be used for building tag-based navigation, content filtering, and topic-specific landing pages.

**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with the tag's recent blog posts. This adds a `recent_posts` array containing up to 10 of the most recently published posts tagged with this tag, perfect for creating comprehensive tag pages that showcase both tag information and the latest related content.


## OpenAPI

````yaml /api/openapi/read_api.yaml get /tags/{slug}/
openapi: 3.1.0
info:
  title: ButterCMS Read API
  version: 2.0.0
  description: >
    Read endpoints for the ButterCMS API — Pages, Collections, Blog Posts, Blog
    Metadata, and Feeds.
  contact:
    email: support@buttercms.com
  license:
    name: ButterCMS Terms of Service
    url: https://buttercms.com/terms/
servers:
  - url: https://api.buttercms.com/v2
    description: ButterCMS API v2
security:
  - readTokenAuthHeader: []
  - readTokenAuthQuery: []
tags:
  - name: Pages
    description: >
      Retrieve pages from your ButterCMS account.


      **Single Pages**: Use `*` as the page_type to get Single Pages (those
      without a Page Type) which represent unique pages on your site like your
      Homepage. Useful for creating your sitemap.xml.


      **Page Type Pages**: Use the actual page type slug to get pages of that
      specific type. Page Types allow you to create many pages with the same
      structure.


      **Note:** The fields of a page are defined by you, they are customizable.
      Sample responses below contain a basic set of fields for illustrative
      purposes.
  - name: Collections
    description: >
      Retrieve collection items from your ButterCMS account. Collections are
      flexible, user-defined content structures with completely customizable
      field schemas.


      See also: Architecture & Performance for guidance on `levels`, pagination,
      and performance best practices.
  - name: Blog posts
    description: >
      Retrieve blog posts from your ButterCMS account. List blog posts with
      pagination and filtering options, or retrieve individual posts by slug.
  - name: Blog metadata
    description: >
      Retrieve blog-related metadata including authors, categories, and tags.
      These endpoints provide access to the organizational structure of your
      blog content.
  - name: Feeds and utilities
    description: >
      Generate XML feeds for content syndication and SEO.


      - **RSS Feed**: Fully generated RSS 2.0 feed for your blog

      - **Atom Feed**: Standards-compliant Atom 1.0 feed

      - **Sitemap**: XML sitemap for search engine discovery


      All feeds can be filtered by category or tag and include only published
      content from your organization.
  - name: Images - Info
    description: >
      ButterCMS has an integration with
      [Filestack](https://www.filestack.com/docs/api/processing/) for image
      transformations. You can leverage their robust set of image transformation
      capabilities.


      After you upload an image, to create a thumbnail, here's an example:


      - **Original URL**: `https://cdn.buttercms.com/3ccPHhYHTNK2zQ14gCOy`

      - **Thumbnail URL**:
      `https://cdn.buttercms.com/resize=width:100,height:100/3ccPHhYHTNK2zQ14gCOy`


      For complete transformation options and parameters, see the [full
      Filestack documentation](https://www.filestack.com/docs/api/processing/).
paths:
  /tags/{slug}/:
    get:
      tags:
        - Blog metadata
      summary: Retrieve Tag
      description: >
        Retrieve a specific blog post tag by its unique slug identifier,
        providing detailed tag information and optional recent posts
        integration. Tags provide granular categorization and labeling for blog
        content, enabling detailed content organization and enhanced discovery
        capabilities.


        **Tag Information**: The tag object contains the display name (e.g.,
        "API Development") and URL-friendly slug identifier (e.g.,
        "api-development") that can be used for building tag-based navigation,
        content filtering, and topic-specific landing pages.


        **Recent Posts Integration**: Use the `include=recent_posts` parameter
        to enrich the response with the tag's recent blog posts. This adds a
        `recent_posts` array containing up to 10 of the most recently published
        posts tagged with this tag, perfect for creating comprehensive tag pages
        that showcase both tag information and the latest related content.
      operationId: retrieveTag
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          description: |
            The unique slug identifier of the tag to retrieve.
          example: api-development
        - $ref: '#/components/parameters/auth_token'
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - recent_posts
          description: >
            Include additional data in the response.


            When set to `recent_posts`, the tag object will include a
            `recent_posts` array containing the latest blog posts tagged with
            this tag (up to 10 posts, ordered by most recent first).
          example: recent_posts
        - name: locale
          in: query
          description: >
            Filter the embedded `recent_posts` list to posts in the given locale
            (e.g. `en`, `es`). The tag itself is shared across locales and is
            always returned. When omitted, defaults to your organization's
            default locale.


            Returns `400` if the value is not a locale configured on your
            organization.
          required: false
          schema:
            type: string
            maxLength: 10
          example: en
      responses:
        '200':
          description: Tag retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveTagResponse'
              examples:
                basic_tag:
                  summary: Basic tag without recent posts
                  value:
                    data:
                      name: API Development
                      slug: api-development
                tag_with_posts:
                  summary: Tag with recent posts included
                  value:
                    data:
                      name: API Development
                      slug: api-development
                      recent_posts:
                        - slug: rest-api-best-practices
                          title: REST API Best Practices for Modern Development
                          published: '2024-01-22T09:00:00.000Z'
                        - slug: graphql-vs-rest
                          title: 'GraphQL vs REST: Choosing the Right API'
                          published: '2024-01-18T14:30:00.000Z'
                        - slug: api-versioning-strategies
                          title: API Versioning Strategies for Long-term Success
                          published: '2024-01-14T16:15:00.000Z'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          description: Not Found - Tag with specified slug does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                tag_not_found:
                  summary: Tag not found
                  value:
                    detail: Not found.
      security:
        - readTokenAuthHeader: []
        - readTokenAuthQuery: []
components:
  parameters:
    auth_token:
      name: auth_token
      in: query
      required: false
      schema:
        type: string
      description: |
        Your ButterCMS read API token
      example: your_api_token
  schemas:
    RetrieveTagResponse:
      type: object
      description: Response structure for retrieving a single tag
      properties:
        data:
          $ref: '#/components/schemas/TagObjectWithPosts'
          description: Single tag object
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message describing what went wrong
          example: Authentication credentials were not provided
    TagObjectWithPosts:
      type: object
      description: Tag information with optional recent posts
      properties:
        name:
          type: string
          description: Display name of the tag
          example: API Development
        slug:
          type: string
          description: URL-friendly slug of the tag
          example: api-development
        recent_posts:
          type: array
          items:
            $ref: '#/components/schemas/TagRecentPost'
          description: >-
            Array of recent posts with this tag (only included when
            include=recent_posts parameter is used)
    TagRecentPost:
      type: object
      description: Simplified blog post information for tag's recent posts
      properties:
        slug:
          type: string
          description: Blog post slug/identifier
          example: rest-api-best-practices
        title:
          type: string
          description: Blog post title
          example: REST API Best Practices for Modern Development
        published:
          type: string
          format: date-time
          description: Publication date and time in ISO 8601 format
          example: '2024-01-22T09:00:00.000Z'
  responses:
    UnauthorizedResponse:
      description: Unauthorized - Invalid or missing API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_token:
              summary: Missing API token
              value:
                detail: Authentication credentials were not provided
            invalid_token:
              summary: Invalid API token
              value:
                detail: Invalid token
  securitySchemes:
    readTokenAuthHeader:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Set the `Authorization` header to `Token your_read_api_token`.

        Example: `Authorization: Token abc123def456`

        Note: The header value includes the `Token` prefix.

        You can access your API token from your settings page.
    readTokenAuthQuery:
      type: apiKey
      in: query
      name: auth_token
      description: >
        Pass your API token via the `auth_token` parameter on every request:
        `?auth_token=your_read_api_token`.


        You can access your API token from your settings page.


        Requests made with a missing or invalid token will get a 401
        Unauthorized response. All requests must be made over HTTPS.

````