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

# List transactions by tag

>  

Use this endpoint to get a list of all transactions associated with a particular tag  according to the tag's unique GUID. This lists all transactions that have been assigned to a particular  tag using the create tagging endpoint. <br /><br />Enhanced transaction data may be requested using the  `includes` parameter. To use this optional parameter, the value should include the optional metadata  requested such as `repeating_transactions`, `merchants`, `classifications`, `geolocations`. For more  information, see the [Optional Enhancement Query Parameter guide](/api-reference/platform-api/reference/transactions#enhanced-transactions).


## OpenAPI

````yaml openapi/platform-api/v20111101.yaml GET /users/{user_guid}/tags/{tag_guid}/transactions
openapi: 3.0.0
info:
  contact:
    name: MX Platform API
    url: https://www.mx.com/products/platform-api
  description: >
    The MX Platform API is a powerful, fully-featured API designed to make
    aggregating and enhancing financial data easy and reliable. It can
    seamlessly connect your app or website to tens of thousands of financial
    institutions.
  title: MX Platform API
  version: '20111101'
servers:
  - url: https://int-api.mx.com
  - url: https://api.mx.com
security:
  - basicAuth: []
tags:
  - name: authorization
  - name: widgets
  - name: users
  - name: members
  - name: institutions
  - name: accounts
  - name: transactions
  - name: microdeposits
  - name: managed data
  - name: transaction rules
  - name: statements
  - name: merchants
  - name: categories
  - name: insights
  - name: investment holdings
  - name: spending plan
  - name: goals
  - name: budgets
  - name: monthly cash flow profile
  - name: notifications
  - name: taggings
  - name: tags
  - name: deprecated
  - name: processor token
  - name: verifiable credentials
  - name: rewards
  - name: ach return
paths:
  /users/{user_guid}/tags/{tag_guid}/transactions:
    get:
      tags:
        - transactions
      summary: List transactions by tag
      description: >-
        Use this endpoint to get a list of all transactions associated with a
        particular tag  according to the tag's unique GUID. This lists all
        transactions that have been assigned to a particular  tag using the
        create tagging endpoint. <br /><br />Enhanced transaction data may be
        requested using the  `includes` parameter. To use this optional
        parameter, the value should include the optional metadata  requested
        such as `repeating_transactions`, `merchants`, `classifications`,
        `geolocations`. For more  information, see the [Optional Enhancement
        Query Parameter
        guide](/api-reference/platform-api/reference/transactions-overview#enhanced-transactions#optional-enhancement-query-parameter).
      operationId: listTransactionsByTag
      parameters:
        - $ref: '#/components/parameters/userGuid'
        - $ref: '#/components/parameters/tagGuid'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/recordsPerPageMax1000'
        - $ref: '#/components/parameters/fromDate'
        - $ref: '#/components/parameters/toDate'
        - $ref: '#/components/parameters/fromCreatedAt'
        - $ref: '#/components/parameters/toCreatedAt'
        - $ref: '#/components/parameters/fromUpdatedAt'
        - $ref: '#/components/parameters/toUpdatedAt'
        - $ref: '#/components/parameters/categoryGuidQuery'
        - $ref: '#/components/parameters/categoryGuidQueryArray'
        - $ref: '#/components/parameters/topLevelCategoryGuid'
        - $ref: '#/components/parameters/topLevelCategoryGuidArray'
        - $ref: '#/components/parameters/useCase'
        - $ref: '#/components/parameters/includes'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/TransactionsResponseBodyIncludes'
          description: OK
components:
  parameters:
    userGuid:
      description: The unique identifier for a `user`, beginning with the prefix `USR-`.
      example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
      in: path
      name: user_guid
      required: true
      schema:
        type: string
    tagGuid:
      description: The unique id for a `tag`.
      example: TAG-aef36e72-6294-4c38-844d-e573e80aed52
      in: path
      name: tag_guid
      required: true
      schema:
        type: string
    page:
      description: Results are paginated. Specify current page.
      example: 1
      in: query
      name: page
      schema:
        type: integer
    recordsPerPageMax1000:
      description: >-
        This specifies the number of records to be returned on each page.
        Defaults to `25`. The valid range is from `10` to `1000`. If the value
        exceeds `1000`, the default value of `25` will be used instead.
      example: 10
      in: query
      name: records_per_page
      schema:
        type: integer
    fromDate:
      description: >-
        Filter transactions from this date. This only supports ISO 8601 format
        without timestamp (YYYY-MM-DD). Defaults to 120 days ago if not
        provided.
      example: '2024-01-01'
      in: query
      name: from_date
      schema:
        type: string
    toDate:
      description: >-
        Filter transactions to this date (at midnight). This only supports ISO
        8601 format without timestamp (YYYY-MM-DD). Defaults to 5 days forward
        from the day the request is made to capture pending transactions.
      example: '2024-03-31'
      in: query
      name: to_date
      schema:
        type: string
    fromCreatedAt:
      name: from_created_at
      in: query
      description: >-
        Filter transactions from the date the transaction was created. This only
        supports ISO 8601 format without timestamp (YYYY-MM-DD). Maximum date
        range limit is 6 months.
      example: '2024-01-01'
      schema:
        type: string
    toCreatedAt:
      name: to_created_at
      description: >-
        Filter transaction to the date in which the transaction was created.
        This only supports ISO 8601 format without timestamp (YYYY-MM-DD).
        Maximum date range limit is 6 months.
      example: '2024-03-31'
      in: query
      schema:
        type: string
    fromUpdatedAt:
      name: from_updated_at
      description: >-
        Filter transactions from the date in which the transaction was updated.
        This only supports ISO 8601 format without timestamp (YYYY-MM-DD).
        Maximum date range limit is 6 months.
      example: '2024-01-01'
      in: query
      schema:
        type: string
    toUpdatedAt:
      name: to_updated_at
      description: >-
        Filter transactions to the date in which the transaction was updated.
        This only supports ISO 8601 format without timestamp (YYYY-MM-DD).
        Maximum date range limit is 6 months.
      example: '2024-03-31'
      in: query
      schema:
        type: string
    categoryGuidQuery:
      name: category_guid
      description: |-
        Filter transactions belonging to specified `category_guid`.

        For example, `?category_guid=CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874`.
      in: query
      schema:
        type: string
    categoryGuidQueryArray:
      name: category_guid[]
      description: >-
        Filter transactions belonging to any specified `category_guid[]` in url.


        For example,
        `?category_guid[]=CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874`.
      in: query
      schema:
        type: array
        items:
          type: string
    topLevelCategoryGuid:
      name: top_level_category_guid
      description: >-
        Filter transactions belonging to specified `top_level_category_guid`.
        This must be top level category guid, use `category_guid` for
        subcategory guid.


        For example,
        `?top_level_category_guid=CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874`.
      in: query
      schema:
        type: string
    topLevelCategoryGuidArray:
      name: top_level_category_guid[]
      description: >-
        Filter transactions belonging to any specified
        `top_level_category_guid[]` in url. This must be top level category
        guid(s), use `category_guid` for subcategory guid(s).


        For example,
        `?top_level_category_guid[]=CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874`.
      in: query
      schema:
        type: array
        items:
          type: string
    useCase:
      description: >-
        The use case associated with the member. Valid values are `PFM` and
        `MONEY_MOVEMENT`. For example, you can append either `?use_case=PFM` or
        `?use_case=MONEY_MOVEMENT`.
      example: MONEY_MOVEMENT
      required: false
      in: query
      name: use_case
      schema:
        type: string
    includes:
      description: >
        Options for enhanced transactions. This query parameter is optional.
        Possible additional metadata: `repeating_transactions`, `merchants`,
        `classifications`, `geolocations`. The query value is format sensitive.
        To retrieve all available enhancements, append:


        `?includes=repeating_transactions,merchants,classifications,geolocations`. 
         
        The query options may be combined to specific enhancements. For example,
        to request Repeating Transactions and Geolocation data, use: 


        `?includes=repeating_transactions,geolocations`.


        - Repeating Transactions: Identifies transactions with predictable
        recurrence patterns (e.g., Bill, Income, Subscription).

        - Merchants: Enriches transactions with merchant name.

        - Classifications: Provides more insight into the type of money movement
        that is occurring on the transaction, whether it be retail or
        investments.

        - Geolocation: Provides geographic metadata.
      example: repeating_transactions,merchants,classifications,geolocations
      in: query
      name: includes
      required: false
      schema:
        type: string
  schemas:
    TransactionsResponseBodyIncludes:
      properties:
        transactions:
          items:
            $ref: '#/components/schemas/TransactionIncludesResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      type: object
    TransactionIncludesResponse:
      allOf:
        - $ref: '#/components/schemas/TransactionResponse'
        - properties:
            classification:
              type: object
              nullable: true
              properties:
                parent_class:
                  example: Deposit
                  type: string
                  enum:
                    - Payroll
                    - Deposit
                    - Savings
                    - Transfer
                    - Refunds
                    - Spend
                    - Investment
                    - Buy
                    - Sell
                    - Income
                    - Fees
                    - Expenses
                    - Corporate Actions
                    - Other
                guid:
                  example: MNC-3ad50f86-60d0-4545-a1f9-e66c2ac40f69
                  type: string
            geolocation:
              nullable: true
              type: object
              properties:
                country:
                  example: us
                  type: string
                state:
                  example: UT
                  type: string
                city:
                  example: lehi
                  type: string
                postal code:
                  example: '84043'
                  type: string
            merchant:
              type: object
              nullable: true
              properties:
                name:
                  example: MX
                  type: string
                guid:
                  example: MCH-0c25f895-393c-42a4-9c18-95a0b26d4d84
                  type: string
                logo_url:
                  type: string
                  example: >-
                    https://content.mx.com/logos/merchants/MCH-0c25f895-393c-42a4-9c18-95a0b26d4d84.png
                website_url:
                  type: string
                  example: https://www.mx.com
            repeating_transaction:
              nullable: true
              type: object
              properties:
                repeating_transaction_type:
                  type: string
                  enum:
                    - BILL
                    - SUBSCRIPTION
                    - INCOME
                    - UNKNOWN
                recurrence_type:
                  type: string
                  enum:
                    - EVERY_OTHER_WEEK
                guid:
                  type: string
                  example: RPT-065b8b1d-826a-45ce-8487-60ca1510e72a
      type: object
    PaginationResponse:
      properties:
        current_page:
          example: 1
          type: integer
        per_page:
          example: 25
          type: integer
        total_entries:
          example: 1
          type: integer
        total_pages:
          example: 1
          type: integer
      type: object
    TransactionResponse:
      properties:
        account_guid:
          example: ACT-0af29528-bb91-447f-b5de-85c1c42593e5
          nullable: true
          type: string
        account_id:
          example: FdvkkAgLS0nbDNUujrblz6rYDSl5w-tTLwYRgIxe7jw
          nullable: true
          type: string
        amount:
          example: 5003.9
          nullable: true
          type: number
        category:
          example: Paycheck
          nullable: true
          type: string
        category_guid:
          example: CAT-982ea9e6-3f0e-0c5b-611b-6657a10ba819
          nullable: true
          type: string
        check_number_string:
          example: null
          nullable: true
          type: string
        created_at:
          example: '2024-12-20T18:52:36Z'
          nullable: true
          type: string
        currency_code:
          example: null
          nullable: true
          type: string
        date:
          example: '2024-12-20'
          nullable: true
          type: string
        description:
          example: MX Technologies
          nullable: true
          type: string
        extended_transaction_type:
          example: null
          nullable: true
          type: string
        guid:
          example: TRN-429ad9fe-a1d2-4559-8590-885b2603f0e1
          nullable: true
          type: string
        id:
          example: 1734681600000-178fa8095c154a55b9172f977b4c5f9a-0
          nullable: true
          type: string
        is_bill_pay:
          example: false
          nullable: true
          type: boolean
        is_direct_deposit:
          example: false
          nullable: true
          type: boolean
        is_expense:
          example: false
          nullable: true
          type: boolean
        is_fee:
          example: false
          nullable: true
          type: boolean
        is_income:
          example: true
          nullable: true
          type: boolean
        is_international:
          example: null
          nullable: true
          type: boolean
        is_manual:
          example: false
          nullable: true
          type: boolean
        is_overdraft_fee:
          example: false
          nullable: true
          type: boolean
        is_payroll_advance:
          example: false
          nullable: true
          type: boolean
        is_recurring:
          example: null
          nullable: true
          type: boolean
        is_subscription:
          example: false
          nullable: true
          type: boolean
        latitude:
          example: null
          nullable: true
          type: number
        localized_description:
          example: null
          nullable: true
          type: string
        localized_memo:
          example: null
          nullable: true
          type: string
        longitude:
          example: null
          nullable: true
          type: number
        member_guid:
          example: MBR-78b14c5f-7297-4fb5-a966-65ac45f74d8
          nullable: true
          type: string
        member_is_managed_by_user:
          example: true
          nullable: true
          type: boolean
        memo:
          example: Transactions
          nullable: true
          type: string
        merchant_category_code:
          example: null
          nullable: true
          type: integer
        merchant_guid:
          example: MCH-8cc3b01a-1c52-47d4-970d-30f8ee5566f1
          nullable: true
          type: string
        merchant_location_guid:
          example: null
          nullable: true
          type: string
        metadata:
          example: null
          nullable: true
          type: string
        original_description:
          example: MX TECHNOLOGIES PAYMENT
          nullable: true
          type: string
        posted_at:
          example: '2024-12-20T12:00:00Z'
          nullable: true
          type: string
        status:
          example: POSTED
          nullable: true
          type: string
        top_level_category:
          example: Income
          nullable: true
          type: string
        transacted_at:
          example: '2024-12-20T12:00:00Z'
          nullable: true
          type: string
        type:
          type: string
          nullable: true
          example: CREDIT
        updated_at:
          example: '2024-12-20T18:52:38Z'
          nullable: true
          type: string
        user_guid:
          example: USR-ef7a82f6-d6c1-42c4-9061-bdece5c4d44e
          nullable: true
          type: string
        user_id:
          example: null
          nullable: true
          type: string
      type: object
  securitySchemes:
    basicAuth:
      scheme: basic
      type: http

````