NerdGraph tutorial: Create and manage Pathpoint flows

preview

We're still working on this feature, but we'd love for you to try it out!

This feature is currently provided as part of a preview program pursuant to our pre-release policies.

You can use our NerdGraph API to create and manage Pathpoint flows programmatically, instead of building them in the UI.

A flow represents one business journey, such as checkout, authentication, or onboarding. It's the unit you create and manage through the API. Flows are entities, so each one has an entity GUID you use to read, update, or delete it.

Every flow follows a four-tier hierarchy, with KPIs attached at the flow level, the stage level, or both:

Flow
├── Flow KPIs
└── Stages
    ├── Stage KPIs
    └── Levels
        └── Steps
            └── Signals (entity GUIDs, alert condition GUIDs, or a dynamic query)

For an introduction to Pathpoint itself, see Get started with Pathpoint.

Before you begin

You need:

Pathpoint enabled on your account.
A New Relic to authenticate your requests.
Your account ID.

Flow operations

To run these examples interactively, open the NerdGraph GraphiQL explorer and search the schema for pathPoint. Before running an example, replace its placeholders with your own values: YOUR_ACCOUNT_ID, TARGET_ACCOUNT_ID, FLOW_GUID, SOURCE_FLOW_GUID, ENTITY_GUID, ANOTHER_ENTITY_GUID, ENTITY_NAME, ALERT_CONDITION_GUID, and the stage, level, and step IDs.

Create a flow

Create a flow by passing its nested stages, levels, steps, and signals in a single mutation.

This creates a "Checkout flow" with one stage, "Frontend," containing three steps. "Login page" matches entities with a dynamic query, "Cart service" pins one specific entity by GUID, and "Checkout errors" pins an alert condition.

mutation {
  pathPointCreate(
    scope: { id: YOUR_ACCOUNT_ID, type: ACCOUNT }
    pathpoint: {
      name: "Checkout flow"
      description: "End-to-end checkout journey"
      category: "E-Commerce"
      refreshInterval: FIVE_MINUTES
      stages: [
        {
          name: "Frontend"
          healthRollup: AUTOMATIC_ROLL_UP
          levels: [
            {
              steps: [
                {
                  name: "Login page"
                  entitySearchQuery: {
                    query: "domain = 'BROWSER' AND type = 'APPLICATION' AND name = 'Login'"
                  }
                }
                {
                  name: "Cart service"
                  signals: [
                    { guid: "ENTITY_GUID", name: "Cart service", type: ENTITY }
                  ]
                }
                {
                  name: "Checkout errors"
                  signals: [
                    {
                      guid: "ALERT_CONDITION_GUID"
                      name: "Checkout error rate"
                      type: ALERT
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ) {
    guid
    name
    version
    message
    excludedKpis
    stages {
      totalCount
      items {
        id
        name
        levels {
          items {
            id
            steps {
              items {
                id
                name
              }
            }
          }
        }
      }
    }
  }
}

KPIs at the top level apply to the whole flow. KPIs inside a stage (stageKpis) apply to that stage only. Both use the same schema.

Each KPI's timeWindow takes either a relativeRange built from fixed durations or a customRange holding a raw NRQL time expression, not both.

mutation {
  pathPointCreate(
    scope: { id: YOUR_ACCOUNT_ID, type: ACCOUNT }
    pathpoint: {
      name: "Checkout flow"
      refreshInterval: FIVE_MINUTES
      kpis: [
        {
          name: "Order success rate"
          category: "Revenue"
          description: "Orders completed successfully"
          query: {
            from: "Transaction"
            where: "transactionType = 'Web' AND name = 'checkout'"
            select: { aggregationType: COUNT, alias: "orders" }
            timeWindow: {
              relativeRange: {
                since: TWENTY_FOUR_HOURS
                compareAgainst: SEVEN_DAYS
              }
            }
          }
        }
      ]
      stages: [
        {
          name: "Payment"
          stageKpis: [
            {
              name: "Payment errors"
              category: "Reliability"
              query: {
                from: "TransactionError"
                select: { aggregationType: COUNT, alias: "errors" }
                timeWindow: { customRange: "SINCE 30 minutes ago" }
              }
            }
          ]
          levels: [
            {
              steps: [
                {
                  name: "Payment gateway"
                  config: {
                    healthRollup: WORST_STATUS_WINS
                    thresholdType: FIXED
                    thresholdValue: 1
                  }
                  entitySearchQuery: {
                    query: "domain = 'APM' AND name = 'PaymentGateway'"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ) {
    guid
    name
    version
    excludedKpis
    kpis {
      id
      name
      category
      query {
        from
        where
        select {
          aggregationType
          attribute
          alias
        }
        timeWindow {
          customRange
          relativeRange {
            since
            compareAgainst
          }
        }
      }
    }
  }
}

A flow and each of its stages calculate health in one of two ways, which you set with a healthRollup field at that level.

At the flow level, healthRollup controls how the flow's overall health is derived:

Automatic rollup (AUTOMATIC_ROLL_UP, the default): Health rolls up automatically from the flow's stages. Set isExcluded: true on a stage to leave it out of the flow's overall health. That stage's own levels, steps, and signals are still evaluated and still appear in the UI. The stage just stops affecting the flow's status, which is useful for stages under construction or temporarily out of scope. isExcluded: false, the default, means the stage participates normally.

Alert conditions (ALERT_CONDITIONS): Health comes from the alert conditions on the flow's KPIs instead of from stage rollup. Pair it with flow-level kpis.

The same two methods apply at the stage level, set with a healthRollup field on the stage itself. AUTOMATIC_ROLL_UP rolls up from that stage's levels, through their steps and signals; set isExcluded: true on a step, signal, or entitySearchQuery to leave it out of that calculation. ALERT_CONDITIONS ties the stage's health to one of its own KPIs (stageKpis) instead, which suits a stage whose status should reflect a business outcome rather than step and signal telemetry, such as an email open rate KPI on a marketing campaigns stage.

The flow-level and stage-level settings are independent, so a flow can use one method while its stages use the other.

This example creates a "Checkout flow" that uses AUTOMATIC_ROLL_UP for its own overall health, with two stages. "Revenue" uses ALERT_CONDITIONS tied to a "Payment errors" KPI, and "Frontend" uses AUTOMATIC_ROLL_UP while excluding one signal from health.

mutation {
  pathPointCreate(
    scope: { id: YOUR_ACCOUNT_ID, type: ACCOUNT }
    pathpoint: {
      name: "Checkout flow"
      description: "End-to-end checkout pipeline"
      refreshInterval: FIVE_MINUTES
      healthRollup: AUTOMATIC_ROLL_UP
      stages: [
        {
          name: "Revenue"
          healthRollup: ALERT_CONDITIONS
          related: { source: false, target: true }
          stageKpis: [
            {
              name: "Payment errors"
              category: "Reliability"
              query: {
                from: "TransactionError"
                select: { aggregationType: COUNT, alias: "errors" }
              }
            }
          ]
          levels: [
            {
              steps: [
                {
                  name: "Order service"
                  config: { healthRollup: WORST_STATUS_WINS }
                  entitySearchQuery: {
                    query: "domain = 'APM' AND name = 'OrderService'"
                  }
                }
              ]
            }
          ]
        }
        {
          name: "Frontend"
          healthRollup: AUTOMATIC_ROLL_UP
          related: { source: true, target: false }
          levels: [
            {
              steps: [
                {
                  name: "Login page"
                  config: {
                    healthRollup: WORST_STATUS_WINS
                    thresholdType: FIXED
                    thresholdValue: 1
                  }
                  entitySearchQuery: {
                    query: "domain = 'BROWSER' AND name = 'Login'"
                  }
                  signals: [
                    {
                      guid: "ENTITY_GUID"
                      name: "ENTITY_NAME"
                      type: ENTITY
                      isExcluded: true
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ) {
    guid
    name
    message
  }
}

pathPointCreate requires the account scope. Within the payload, only name is required. Everything else, including stages, is optional. A step gets its signals in one of three ways, and you can combine them:

A dynamic query (entitySearchQuery): Whatever entities match the query, re-evaluated at each refresh.
A pinned entity (type: ENTITY): One specific entity, identified by its GUID.
A pinned alert condition (type: ALERT): One alert condition, identified by its GUID.

The type field is optional. The GUID is enough to identify the signal.

Stages also take an optional related block that controls how the UI draws the connector arrows between them, independent of health rollup. Set source: true if a stage should show an incoming arrow from the stage before it, and target: true if it should show an outgoing arrow to the stage after it. In a flow where every stage connects to the next in sequence, the first stage is source: false, target: true, the last is source: true, target: false, and every stage in between is true for both.

Importante

A KPI's accountId defaults to the flow's account. If you set it to a different account, the KPI isn't created and no error comes back. Check the excludedKpis field in the response to see which KPIs the mutation skipped.

Read a flow

Read a flow by its entity GUID to get its full configuration plus the current health status of the flow, each stage, each level, and each step. healthStatus appears only on reads.

Stages, levels, and steps return 50 items per page. When a nextCursor comes back non-null, pass it to fetch the next page.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      pathPoint {
        flow(guid: "FLOW_GUID") {
          guid
          name
          description
          category
          refreshInterval
          healthRollup
          healthStatus
          version
          message
          kpis {
            id
            name
            category
            accountId
            query {
              from
              where
              select {
                aggregationType
                attribute
                alias
                threshold
              }
              timeWindow {
                customRange
                relativeRange {
                  since
                  compareAgainst
                }
              }
            }
            metricQuery
          }
          stages {
            totalCount
            nextCursor
            items {
              id
              name
              link
              healthRollup
              healthStatus
              isExcluded
              related {
                source
                target
              }
              levels {
                totalCount
                nextCursor
                items {
                  id
                  healthStatus
                  steps {
                    totalCount
                    nextCursor
                    items {
                      id
                      name
                      healthStatus
                      isExcluded
                      scopedAccounts
                      config {
                        healthRollup
                        thresholdType
                        thresholdValue
                      }
                      entitySearchQuery {
                        query
                        isExcluded
                      }
                      signals {
                        guid
                        name
                        type
                        isExcluded
                      }
                    }
                  }
                }
              }
            }
          }
          metadata {
            createdAt
            createdBy {
              name
              email
            }
            updatedAt
            updatedBy {
              name
              email
            }
          }
        }
      }
    }
  }
}

Request fewer fields if you don't need the whole tree. Reading just name and healthStatus, for example, is enough to poll a flow's status.

Update a flow

pathPointUpdate is a diff-based operation. It compares the payload you send against the flow's current state and acts on each stage, level, step, and KPI according to whether you included its ID:

ID included: Updates the existing object.
ID omitted: Creates a new object.
Object left out of the payload entirely: Deletes it from the flow.

Cuidado

Because omission means deletion, always read the flow first, modify the payload you get back, and send the complete intended state. Sending a partial payload deletes everything you left out.

The version field is also required. It's the flow's last-updated timestamp in epoch milliseconds, used for optimistic concurrency control. Omitting it or sending a stale value causes the update to fail.

The first step carries its id, so it updates in place. The second has no id, so it's created as new.

mutation {
  pathPointUpdate(
    guid: "FLOW_GUID"
    pathpoint: {
      name: "Checkout flow"
      refreshInterval: FIVE_MINUTES
      version: 1786624914316
      stages: [
        {
          id: "STAGE_ID"
          name: "Frontend"
          healthRollup: AUTOMATIC_ROLL_UP
          levels: [
            {
              id: "LEVEL_ID"
              steps: [
                {
                  id: "STEP_ID"
                  name: "Cart service"
                  signals: [
                    { guid: "ENTITY_GUID", name: "Cart service", type: ENTITY }
                  ]
                }
                {
                  name: "Recommendation service"
                  signals: [
                    {
                      guid: "ANOTHER_ENTITY_GUID"
                      name: "Recommendation service"
                      type: ENTITY
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ) {
    guid
    name
    version
    message
    stages {
      totalCount
      items {
        id
        name
        levels {
          items {
            id
            steps {
              items {
                id
                name
              }
            }
          }
        }
      }
    }
  }
}

Duplicate a flow

You can duplicate either the structure alone or the whole flow:

STRUCTURE: Copies stages, levels, and steps only, without signals or KPIs.
WHOLE_FLOW: Copies the structure along with its signals and KPIs.

Any property you set in the input overrides the source flow's value. Omit a property to inherit it.

To duplicate within the same account, you don't need a scope argument. Set duplicateType: WHOLE_FLOW.

mutation {
  pathPointDuplicate(
    sourceGuid: "SOURCE_FLOW_GUID"
    pathpoint: {
      name: "Checkout flow (copy)"
      category: "E-Commerce"
      refreshInterval: TEN_MINUTES
      duplicateType: WHOLE_FLOW
    }
  ) {
    guid
    name
  }
}

To copy a flow into a different account, add a scope and set its id to the target account. Omit scope to duplicate within the source account.

Duplicating into another account copies only stages, levels, steps, and signals, not KPIs.

mutation {
  pathPointDuplicate(
    sourceGuid: "SOURCE_FLOW_GUID"
    scope: { id: TARGET_ACCOUNT_ID, type: ACCOUNT }
    pathpoint: { name: "Checkout flow", duplicateType: WHOLE_FLOW }
  ) {
    guid
    name
  }
}

Set duplicateType: STRUCTURE to copy only the flow's shape, without its signals or KPIs.

mutation {
  pathPointDuplicate(
    sourceGuid: "SOURCE_FLOW_GUID"
    pathpoint: {
      name: "Checkout flow (copy)"
      category: "E-Commerce"
      refreshInterval: TEN_MINUTES
      duplicateType: STRUCTURE
    }
  ) {
    guid
    name
  }
}

Delete a flow

Deleting a flow cascades: it removes the flow along with all its stages, levels, steps, and KPIs. The signals themselves, the entities and alert conditions the flow pointed at, stay in your account.

Cuidado

Deleting a flow is permanent.

mutation {
  pathPointDelete(guid: "FLOW_GUID") {
    guid
    name
  }
}

Partial failures

A create or update can succeed overall while individual objects fail. Two fields in the response tell you when that happened:

message: Details of any stages, levels, or steps that failed. It's null when everything succeeded.
excludedKpis: The names of KPIs that weren't created, most commonly because the KPI's accountId didn't match the flow's account.

Request both fields in your mutations so you don't treat a partial success as a complete one.

Limits

The following limits apply to every flow, whether you build it through the API or in the UI:

Limit	Value
Maximum stages per flow	50
Maximum levels per stage	50
Maximum steps per level	50
Maximum items returned per page	50

Type reference

These enums appear in the operations above. Each row lists the accepted values, followed by what they control:

Enum	Values
`PathPointRefreshInterval`	`ONE_MINUTE`, `FIVE_MINUTES`, `TEN_MINUTES`, `FIFTEEN_MINUTES`, `THIRTY_MINUTES`. How often flow, stage, level, and step health refresh.
`PathPointFlowHealthRollup`, `PathPointStageHealthRollup`	`AUTOMATIC_ROLL_UP`, `ALERT_CONDITIONS`. Whether health rolls up from child objects, or comes from the worst alert condition across the flow's or stage's KPIs.
`PathPointStepHealthRollup`	`WORST_STATUS_WINS`, `BEST_STATUS_WINS`. Whether the step takes its least healthy signal or its healthiest.
`PathPointThresholdType`	`FIXED`, `PERCENTAGE`. Whether `thresholdValue` is an absolute count or a percentage of signals.
`PathPointStatusValue`	`OPERATIONAL`, `DEGRADED`, `DISRUPTED`, `UNKNOWN`. Computed health, returned on reads.
`PathPointSignalType`	`ENTITY`, `ALERT`. Whether the GUID points to a monitored entity, such as an APM service or host, or to an alert condition.
`PathPointKpiNrqlAggregations`	`COUNT`, `SUM`, `AVERAGE`, `MAX`, `MIN`, `UNIQUE_COUNT`, `PERCENTILE`, `HISTOGRAM`. The aggregation a KPI query applies. Every function except `COUNT` needs an `attribute`.
`PathPointKpiTimeDuration`	`THIRTY_MINUTES`, `SIXTY_MINUTES`, `THREE_HOURS`, `SIX_HOURS`, `TWENTY_FOUR_HOURS`, `SEVEN_DAYS`, `THIRTY_DAYS`. Durations for a KPI's `since` and `compareAgainst`.
`PathPointDuplicateType`	`STRUCTURE`, `WHOLE_FLOW`. Whether to copy stages, levels, and steps only, or the structure along with its signals and KPIs.

Get started with Pathpoint

Learn what Pathpoint is and how to access it.

Create and manage flows

Build and configure flows in the UI.

Introduction to NerdGraph

Learn how to use New Relic's GraphQL API.

NerdGraph tutorial: Create and manage Pathpoint flows

preview

Before you begin

Flow operations

Create a flow

Create a flow with three steps

Create a flow with KPIs

Health rollup calculation

Importante

Read a flow

Update a flow

Cuidado

Add a step while keeping existing objects

Duplicate a flow

Duplicate a whole flow in the same account

Duplicate a whole flow into another account

Duplicate a flow's structure

Delete a flow

Cuidado

Partial failures

Limits

Type reference

Get started with Pathpoint

Create and manage flows

Introduction to NerdGraph

NerdGraph tutorial: Create and manage Pathpoint flows

preview

Before you begin .css-21sua1{background:none;border:none;width:0;padding:0;}

Flow operations

Create a flow

Create a flow with KPIs

Health rollup calculation

Importante

Read a flow

Update a flow

Cuidado

Add a step while keeping existing objects

Duplicate a flow

Duplicate a whole flow in the same account

Duplicate a whole flow into another account

Duplicate a flow's structure

Delete a flow

Cuidado

Partial failures

Limits

Type reference

Related topics

Get started with Pathpoint

Create and manage flows

Introduction to NerdGraph

Before you begin