---
updatedAt: 2026-05-27T16:52:24.000Z
agentTools:
  projectIndex: https://developer.bill.com/llms.txt
---

# Get list of budget members

Get a list of user members assigned to an existing budget. By default, you get 20 results on one page of results. Set `max` in your request to get up to 100 results on one page.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "BILL v3 API",
    "description": "BILL is a cloud-based financial operations platform for an organization's accounts payable (AP), accounts receivable (AR), and spend & expense (S&E) automation.\n\nThe BILL v3 API gives you access to the same infrastructure that powers the AP, AR, and S&E products. In addition, you can receive real-time event notifications with webhooks.\n\nThe BILL Developer Documentation is available at [developer.bill.com](https://developer.bill.com/docs/home).\n\n## Quickstart\nSign-up and generate a developer key for working with the BILL v3 API. With this key, you can build with the AP, AR, BILL network, and webhook workflows. See [Sandbox API sign up](https://developer.bill.com/docs/api-sandbox-sign-up) for more information.\n\n### Spend & Expense API\nAn API token is required for working with the Spend & Expense API. See [Authentication with Spend & Expense API token](https://developer.bill.com/docs/authentication-with-api-token) for more information.\n\n### BILL v3 API in Postman\nWith this collection, you have access to the BILL v3 API in Postman. When you save your sandbox API credentials as environment variables in Postman, you can simply refer to the variables when you are testing with the BILL v3 API. See [BILL v3 API in Postman](https://developer.bill.com/docs/bill-v3-api-in-postman) for more information.",
    "version": "1"
  },
  "servers": [
    {
      "url": "https://gateway.stage.bill.com/connect",
      "description": "sandbox"
    }
  ],
  "paths": {
    "/v3/spend/budgets/{budgetId}/members": {
      "get": {
        "tags": [
          "budgets"
        ],
        "summary": "Get list of budget members",
        "description": "Get a list of user members assigned to an existing budget. By default, you get 20 results on one page of results. Set `max` in your request to get up to 100 results on one page.",
        "operationId": "listBudgetMembers",
        "parameters": [
          {
            "name": "apiToken",
            "in": "header",
            "schema": {
              "type": "string",
              "description": "Access token for Spend & Expense API authentication",
              "nullable": true,
              "example": "{{api_token}}"
            }
          },
          {
            "name": "budgetId",
            "in": "path",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string",
              "description": "BILL-generated ID or UUID of the budget",
              "example": "{{se_budget_uuid}}"
            }
          },
          {
            "name": "max",
            "in": "query",
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer",
              "description": "Maximum number of results",
              "format": "int64",
              "nullable": true,
              "example": 10
            }
          },
          {
            "name": "nextPage",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Next page of results.\n\nWhen a list has multiple pages, the `nextPage` and `prevPage` values in the response enable you to navigate between the pages of results. Set this field as the `nextPage` value for navigation.",
              "nullable": true
            }
          },
          {
            "name": "prevPage",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Previous page of results. Set this field as the `prevPage` value for navigation.",
              "nullable": true
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Field name and sort order. You can set only one sort field.\n\nThe format is `sort={field}:{sort_order}`.\n\nThe sortable fields are:\n- `name`\n- `spent`",
              "nullable": true,
              "example": "spent:desc"
            }
          },
          {
            "name": "filters",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Field name, operator, and value. You can set multiple filters.\n\nThe format is `filters={field_01}:{op}:{value},{field_02}:{op}:{value}`.\n\nExample: `filters=retired:eq:true`\n\nThe filterable fields are:\n- `retired` - `true` or `false`. Operators: `eq`.",
              "nullable": true,
              "example": "retired:eq:false"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Get list of budget members response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedBudgetMemberResponseDto"
                }
              }
            }
          },
          "4XX": {
            "description": "List of errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BdcError"
                  }
                }
              }
            }
          },
          "5XX": {
            "description": "List of errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BdcError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BdcError": {
        "required": [
          "category",
          "code",
          "severity",
          "timestamp"
        ],
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "code": {
            "type": "string"
          },
          "severity": {
            "$ref": "#/components/schemas/Severity"
          },
          "category": {
            "$ref": "#/components/schemas/Category"
          },
          "message": {
            "type": "string"
          },
          "params": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Param"
            }
          },
          "detail": {
            "type": "string"
          },
          "help": {
            "type": "string"
          }
        }
      },
      "BudgetMemberResponseDto": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string",
            "description": "BILL-generated ID of the user",
            "deprecated": true
          },
          "userUuid": {
            "type": "string",
            "description": "BILL-generated UUID of the user"
          },
          "spent": {
            "type": "number",
            "description": "Total amount spent by the user in the current budget period"
          },
          "limit": {
            "type": "number",
            "description": "Funds assigned to the user in the current budget period"
          },
          "recurringLimit": {
            "type": "number",
            "description": "Funds assigned to the user in all future budget periods"
          },
          "recurring": {
            "type": "boolean",
            "description": "Set as `true` if the user receives the `recurringLimit` funds in all future budget periods."
          },
          "budgetRole": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BudgetRoleType"
              },
              {
                "description": "Budget user role"
              }
            ]
          },
          "name": {
            "type": "string",
            "description": "User display name"
          },
          "retired": {
            "type": "boolean",
            "description": "Set as `true` if the budget member is retired"
          },
          "shareBudgetFunds": {
            "type": "boolean",
            "description": "Set as `true` if all the budget funds are shared with the user"
          }
        },
        "description": "Budget members response."
      },
      "BudgetRoleType": {
        "type": "string",
        "description": "Options for setting a user's role within a budget. DELETE removes the user from the budget.",
        "enum": [
          "MEMBER",
          "OWNER",
          "OBSERVER"
        ]
      },
      "Category": {
        "type": "string",
        "enum": [
          "REQUEST",
          "APPLICATION",
          "SERVER",
          "DOWNSTREAM"
        ]
      },
      "PaginatedBudgetMemberResponseDto": {
        "type": "object",
        "description": "List of budget members with paging references.",
        "allOf": [
          {
            "$ref": "#/components/schemas/PaginationResponseDto_BudgetMemberResponseDto_"
          }
        ]
      },
      "PaginationResponseDto_BudgetMemberResponseDto_": {
        "type": "object",
        "properties": {
          "nextPage": {
            "type": "string",
            "description": "Next page token"
          },
          "prevPage": {
            "type": "string",
            "description": "Previous page token"
          },
          "results": {
            "type": "array",
            "description": "Results",
            "items": {
              "$ref": "#/components/schemas/BudgetMemberResponseDto"
            }
          }
        },
        "description": "Response from a list API request with paging references."
      },
      "Param": {
        "required": [
          "name",
          "value"
        ],
        "type": "object",
        "properties": {
          "additional": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "name": {
            "minLength": 1,
            "type": "string"
          },
          "value": {
            "minLength": 1,
            "type": "string"
          }
        }
      },
      "Severity": {
        "type": "string",
        "enum": [
          "ERROR",
          "WARNING",
          "INFORMATION"
        ]
      }
    }
  }
}
```