Procore Budget Change History API

openapi: 3.2.0
info:
  title: Procore REST Budget Change History API
  version: v1.0/v2.0
  description: Merged from the per-resource OpenAPI documents Procore publishes through its developer portal (https://developers.procore.com/api/v1/resource_groups). Originals are kept verbatim in openapi/_original/resources/.
  x-source: https://developers.procore.com/api/v1/resource_groups
servers:
- url: https://api.procore.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Budget Change History
paths:
  /rest/v2.0/companies/{company_id}/projects/{project_id}/budget_change_history:
    parameters:
    - name: Procore-Company-Id
      in: header
      description: Unique company identifier associated with the Procore User Account.
      required: true
      schema:
        type: integer
    x-compliance-level: full
    get:
      x-doc:
        visibility: public
        stage: ga
        exposure: public
      x-endpoint-type: collection
      summary: List of Budget Change Histories
      description: Returns the list of Budget Change Histories for a given project
      tags:
      - Budget Change History
      parameters:
      - name: company_id
        in: path
        description: Unique identifier for the company.
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        description: Unique identifier for the project.
        schema:
          type: string
      - name: page
        in: query
        description: Page
        required: false
        schema:
          type: integer
      - name: per_page
        in: query
        description: Elements per page
        required: false
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 50
      requestBody:
        content:
          application/json:
            schema:
              description: Request body for fetching change histories with filtering options. All filters within a single filter object are combined with OR condition.
              type: object
              properties:
                filters:
                  type: object
                  description: A collection of named filters to apply to the change history query. Currently only supports the `segments` filter.
                  properties:
                    segments:
                      type: array
                      description: An array of segment filter objects. Each object specifies the segment ID, the tier (if applicable), and the array of segment-option IDs to filter by.
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            description: The segment identifier.
                            example: '18911'
                          tier:
                            type:
                            - string
                            - 'null'
                            description: The tier for the segment (if applicable). Set to `null` if not used.
                            example: '1'
                          values:
                            type: array
                            description: An array of segment-option IDs for the given segment/tier.
                            items:
                              type: string
                              description: A segment-option ID.
                              example: '2'
      responses:
        '200':
          description: OK
          headers:
            Per-Page:
              description: Number of items retrieved per page
              schema:
                type: integer
            Total:
              description: Total number of items to be retrieved
              schema:
                type: integer
            Link:
              description: Link headers for the first, prev, next, and last link
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      budget_code:
                        type: string
                        description: The Work Breakdown Structure (WBS) code of the affected budget line, made up of its segment values concatenated by the company's configured delimiter. Identifies which budget line the change applies to.
                        example: 01-001.C
                      description:
                        type: string
                        description: Human-readable description of the budget code (the WBS line item name).
                        example: Concrete - Labor
                      type:
                        type: string
                        description: Localized label describing which budget entity was changed (for example a budget line item, a forecast value, or a specific column).
                        example: Budget Line Item
                      column:
                        type: string
                        description: Localized name of the budget column whose value changed.
                        example: Original Budget Amount
                      created_at:
                        type: string
                        description: When the change was recorded, returned as a localized, human-readable display string (not ISO 8601). Format depends on the project's locale and timezone.
                        example: Jan 15, 2025 at 09:42 am PST
                      created_by:
                        type: string
                        description: Display name of the user who made the change, formatted for the company.
                        example: Doe, John
                      new_value:
                        type: string
                        description: The column's value after the change, formatted for display (currency, percentage, number, or option label depending on the column).
                        example: $12,500.00
                      old_value:
                        type: string
                        description: The column's value before the change, formatted for display (currency, percentage, number, or option label depending on the column).
                        example: $10,000.00
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: HTTP status in screaming snake case (like BAD_REQUEST)
                      message:
                        type: string
                        description: Human readable message describing error.
                      details:
                        type: array
                        description: Additional information about the error.
                        items:
                          type: object
                          required:
                          - reason_code
                          - message
                          properties:
                            reason_code:
                              type: string
                              description: A machine-readable code that identifies the error specifically enough for the client to interpret what happened and take action.
                              example: BLANK
                            message:
                              type: string
                              description: Human readable message
                              example: Name can't be blank
                            source:
                              type: string
                              description: Source of the error
                              example: name
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: HTTP status in screaming snake case (like BAD_REQUEST)
                      message:
                        type: string
                        description: Human readable message describing error.
                      details:
                        type: array
                        description: Additional information about the error.
                        items:
                          type: object
                          required:
                          - reason_code
                          - message
                          properties:
                            reason_code:
                              type: string
                              description: A machine-readable code that identifies the error specifically enough for the client to interpret what happened and take action.
                              example: BLANK
                            message:
                              type: string
                              description: Human readable message
                              example: Name can't be blank
                            source:
                              type: string
                              description: Source of the error
                              example: name
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: HTTP status in screaming snake case (like BAD_REQUEST)
                      message:
                        type: string
                        description: Human readable message describing error.
                      details:
                        type: array
                        description: Additional information about the error.
                        items:
                          type: object
                          required:
                          - reason_code
                          - message
                          properties:
                            reason_code:
                              type: string
                              description: A machine-readable code that identifies the error specifically enough for the client to interpret what happened and take action.
                              example: BLANK
                            message:
                              type: string
                              description: Human readable message
                              example: Name can't be blank
                            source:
                              type: string
                              description: Source of the error
                              example: name
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: HTTP status in screaming snake case (like BAD_REQUEST)
                      message:
                        type: string
                        description: Human readable message describing error.
                      details:
                        type: array
                        description: Additional information about the error.
                        items:
                          type: object
                          required:
                          - reason_code
                          - message
                          properties:
                            reason_code:
                              type: string
                              description: A machine-readable code that identifies the error specifically enough for the client to interpret what happened and take action.
                              example: BLANK
                            message:
                              type: string
                              description: Human readable message
                              example: Name can't be blank
                            source:
                              type: string
                              description: Source of the error
                              example: name
      x-code-samples:
      - id: node_request
        mimeType: application/json
        title: Node.js
        content: "const request = require('request');\n\nconst options = {\n  method: 'GET',\n  url: 'https://api.procore.com/rest/v2.0/companies/%7Bcompany_id%7D/projects/%7Bproject_id%7D/budget_change_history',\n  qs: {page: 'SOME_INTEGER_VALUE', per_page: 'SOME_INTEGER_VALUE'},\n  headers: {'content-type': 'application/json'},\n  body: {filters: {segments: [{id: '18911', tier: '1', values: ['2']}]}},\n  json: true\n};\n\nrequest(options, function (error, response, body) {\n  if (error) throw new Error(error);\n\n  console.log(body);\n});\n"
      - id: python_python3
        mimeType: application/json
        title: Python3
        content: 'import http.client


          conn = http.client.HTTPSConnection("api.procore.com")


          payload = "{\"filters\":{\"segments\":[{\"id\":\"18911\",\"tier\":\"1\",\"values\":[\"2\"]}]}}"


          headers = { ''content-type'': "application/json" }


          conn.request("GET", "/rest/v2.0/companies/%7Bcompany_id%7D/projects/%7Bproject_id%7D/budget_change_history?page=SOME_INTEGER_VALUE&per_page=SOME_INTEGER_VALUE", payload, headers)


          res = conn.getresponse()

          data = res.read()


          print(data.decode("utf-8"))'
      - id: shell_curl
        mimeType: application/json
        title: Curl
        content: "curl --request GET \\\n  --url 'https://api.procore.com/rest/v2.0/companies/%7Bcompany_id%7D/projects/%7Bproject_id%7D/budget_change_history?page=SOME_INTEGER_VALUE&per_page=SOME_INTEGER_VALUE' \\\n  --header 'content-type: application/json' \\\n  --data '{\"filters\":{\"segments\":[{\"id\":\"18911\",\"tier\":\"1\",\"values\":[\"2\"]}]}}'"
      - id: csharp_httpclient
        mimeType: application/json
        title: C#
        content: "var client = new HttpClient();\nvar request = new HttpRequestMessage\n{\n    Method = HttpMethod.Get,\n    RequestUri = new Uri(\"https://api.procore.com/rest/v2.0/companies/%7Bcompany_id%7D/projects/%7Bproject_id%7D/budget_change_history?page=SOME_INTEGER_VALUE&per_page=SOME_INTEGER_VALUE\"),\n    Content = new StringContent(\"{\\\"filters\\\":{\\\"segments\\\":[{\\\"id\\\":\\\"18911\\\",\\\"tier\\\":\\\"1\\\",\\\"values\\\":[\\\"2\\\"]}]}}\")\n    {\n        Headers =\n        {\n            ContentType = new MediaTypeHeaderValue(\"application/json\")\n        }\n    }\n};\nusing (var response = await client.SendAsync(request))\n{\n    response.EnsureSuccessStatusCode();\n    var body = await response.Content.ReadAsStringAsync();\n    Console.WriteLine(body);\n}"
      x-rate-limit-enabled: true
      x-procore-kong-tags:
      - rate-limit:enabled
      x-changelog:
      - summary: Added endpoint to retrieve Budget's Change Histories
        description: New endpoint to retrieve Budget's Change Histories of a given project.
        endpoint: GET /companies/{company_id}/projects/{project_id}/budget_change_history
        type: new
        breaking: false
        datestamp: '2025-05-09'
        versions:
        - '2.0'
        x-doc:
          visibility: public
          stage: ga
          exposure: public
        link: budget-change-history?version=2.0#list-of-budget-change-histories
      operationId: listOfBudgetChangeHistories
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer