Formula Field

A Formula field defines an aggregation — SUM, AVERAGE, COUNT, MIN, MAX — over the values of other custom fields. Formula fields power chart segments and dashboards: they roll values up across the records in a workspace rather than computing a per-record value. Records are Todo objects and workspaces are Project objects in the API.

Create a Formula field with the createCustomField mutation, passing type: FORMULA. The field is created in the workspace identified by the blue-workspace-id header.

Create

The formula argument on createCustomField is typed JSON, so you pass the formula definition as a free-form object. Use the same shape as the typed FormulaInput (a logic block plus a display block) so the field renders identically to one configured in the app.

mutation CreateFormulaField {
  createCustomField(
    input: {
      name: "Budget Total"
      type: FORMULA
      formula: {
        logic: { text: "Budget Total", html: "<span>Budget Total</span>" }
        display: { type: NUMBER, precision: 2, function: SUM }
      }
    }
  ) {
    id
    name
    type
    formula
  }
}

CreateCustomFieldInput

The workspace is taken from the blue-workspace-id header, not from the input. There is no projectId field on CreateCustomFieldInput.

Formula shape

createCustomField accepts formula as JSON; editCustomField accepts it as the typed FormulaInput. Both expect the same structure:

ChartFunction

FormulaDisplayType

Response

createCustomField returns the created CustomField. The stored definition comes back on formula (typed JSON).

{
  "data": {
    "createCustomField": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "name": "Budget Total",
      "type": "FORMULA",
      "formula": {
        "logic": { "text": "Budget Total", "html": "<span>Budget Total</span>" },
        "display": { "type": "NUMBER", "precision": 2, "function": "SUM" }
      }
    }
  }
}

Returns

A Formula field has no per-record value. The aggregated result is computed asynchronously and exposed on ChartSegment.formulaResult (a Float) when the field is used in a chart — it is not returned on the CustomField itself or on any record.

Full example

A currency formula that averages a numeric field, formatted in US dollars to two decimal places.

mutation CreateRevenueAverage {
  createCustomField(
    input: {
      name: "Average Deal Size"
      description: "Mean value across all deals in this workspace"
      type: FORMULA
      formula: {
        logic: { text: "Average Deal Size", html: "<span>Average Deal Size</span>" }
        display: {
          type: CURRENCY
          currency: { code: "USD", name: "US Dollar" }
          precision: 2
          function: AVERAGE
        }
      }
    }
  ) {
    id
    name
    formula
  }
}

Edit

Use editCustomField to change an existing Formula field. Here formula is the typed FormulaInput (same shape as create, but type-checked by the schema). Pass the field’s id as customFieldId.

mutation UpdateFormulaField {
  editCustomField(
    input: {
      customFieldId: "field_123"
      formula: {
        logic: { text: "Completion Rate", html: "<span>Completion Rate</span>" }
        display: { type: PERCENTAGE, precision: 1, function: AVERAGE }
      }
    }
  ) {
    id
    name
    formula
  }
}

Errors

Permissions

Creating and editing custom fields requires the OWNER or ADMIN role on the workspace. Reading a field’s aggregated result requires view access to the chart or dashboard it appears on.

Related

• Number Field — store a numeric value per record.
• Currency Field — store a monetary value per record.
• Lookup Field — pull and roll up values from referenced records.
• Create a Custom Field — the full createCustomField reference.
• Custom Fields Overview — all field types and shared concepts.