Tracking Plans

A Tracking Plan is a data spec outlining the events and properties you intend to collect across your Segment Sources.

The Segment Tracking Plan feature allows you to validate your expected events against the live events that Segment receives. Segment generates violations when an event doesn’t match the spec’d event in the Tracking Plan.

You can store your Tracking Plans in your Workspace, and connect them to one or more Sources.

Using the Segment Public API, you can create, delete, update, list, and connect Tracking Plans and their Rules.

Migrate from the Config API

The getTrackingPlan endpoint returns the following fields:

Config API Public API
display_name name
name slug
updateTime updatedAt
createTime createdAt

To migrate, replace any use of the Config API endpoints with the Segment Public API counterparts, using the field mappings in the table above.

Add Source to Tracking Plan

Connects a Source to a Tracking Plan.

• When called, this endpoint may generate the Source Modified event in the audit trail.

• In order to successfully call this endpoint, the specified Workspace needs to have the Protocols feature enabled. Please reach out to your customer success manager for more information.

Securitytoken
Request
path Parameters
trackingPlanId
required
string [ 1 .. 255 ]
Example: tp_sprout_rVGCC6WdrNxjCf6JpCHP
Request Body schema:
required
sourceId
required
string (sourceId)

The id of the Source associated with the Tracking Plan.

Config API note: analogous to sourceName.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/tracking-plans/{trackingPlanId}/sources
Request samples
{
  • "sourceId": "qQEHquLrjRDN9j1ByrChyn"
}
Response samples
{
  • "data": {
    }
}

List Sources from Tracking Plan

Lists Sources connected to a Tracking Plan.

• In order to successfully call this endpoint, the specified Workspace needs to have the Protocols feature enabled. Please reach out to your customer success manager for more information.

This endpoint requires the user to have at least the following permission(s):

  • Source Read-only
  • Tracking Plan Read-only
Securitytoken
Request
path Parameters
trackingPlanId
required
string [ 1 .. 255 ]
Example: tp_sprout_rVGCC6WdrNxjCf6JpCHP
query Parameters
required
object (PaginationInput)

Pagination options.

This parameter exists in v1.

Example: pagination=pagination.count=2
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/tracking-plans/{trackingPlanId}/sources
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.trackingPlans.listSourcesFromTrackingPlan('tp_sprout_rVGCC6WdrNxjCf6JpCHP', 'pagination.count=2'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{}

Remove Source from Tracking Plan

Disconnects a Source from a Tracking Plan.

• When called, this endpoint may generate the Source Modified event in the audit trail.

• In order to successfully call this endpoint, the specified Workspace needs to have the Protocols feature enabled. Please reach out to your customer success manager for more information.

Securitytoken
Request
path Parameters
trackingPlanId
required
string [ 1 .. 255 ]
Example: tp_sprout_rVGCC6WdrNxjCf6JpCHP
query Parameters
sourceId
required
string (sourceId)

The id of the Source associated with the Tracking Plan.

Config API note: analogous to sourceName.

This parameter exists in v1.

Example: sourceId=qQEHquLrjRDN9j1ByrChyn
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/tracking-plans/{trackingPlanId}/sources
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.trackingPlans.removeSourceFromTrackingPlan('tp_sprout_rVGCC6WdrNxjCf6JpCHP', 'qQEHquLrjRDN9j1ByrChyn'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Create Tracking Plan

Creates a Tracking Plan.

• In order to successfully call this endpoint, the specified Workspace needs to have the Protocols feature enabled. Please reach out to your customer success manager for more information.

Securitytoken
Request
Request Body schema:
required
name
required
string (name)

The Tracking Plan's name.

Config API note: equal to displayName.

description
string (description)

The Tracking Plan's description.

type
required
string (type)

The Tracking Plan's type.

Enum: "ENGAGE" "LIVE" "PROPERTY_LIBRARY" "RULE_LIBRARY" "TEMPLATE"
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/tracking-plans
Request samples
{
  • "name": "New TP",
  • "type": "LIVE"
}
Response samples
{
  • "data": {
    }
}

List Tracking Plans

Returns a list of Tracking Plans.

• In order to successfully call this endpoint, the specified Workspace needs to have the Protocols feature enabled. Please reach out to your customer success manager for more information.

Securitytoken
Request
query Parameters
type
string (type)

Requests Tracking Plans of a certain type. If omitted, lists all types.

This parameter exists in v1.

Enum: "ENGAGE" "LIVE" "PROPERTY_LIBRARY" "RULE_LIBRARY" "TEMPLATE"
Example: type=LIVE
required
object (PaginationInput)

Pagination options.

This parameter exists in v1.

Example: pagination=pagination.count=2
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/tracking-plans
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.trackingPlans.listTrackingPlans('pagination.count=2'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Delete Tracking Plan

Deletes a Tracking Plan.

• In order to successfully call this endpoint, the specified Workspace needs to have the Protocols feature enabled. Please reach out to your customer success manager for more information.

Securitytoken
Request
path Parameters
trackingPlanId
required
string [ 1 .. 255 ]
Example: tp_sprout_rVGCC6WdrNxjCf6JpCHP
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/tracking-plans/{trackingPlanId}
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.trackingPlans.deleteTrackingPlan('tp_sprout_rVGCC6WdrNxjCf6JpCHP'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Get Tracking Plan

Returns a Tracking Plan.

• In order to successfully call this endpoint, the specified Workspace needs to have the Protocols feature enabled. Please reach out to your customer success manager for more information.

Securitytoken
Request
path Parameters
trackingPlanId
required
string [ 1 .. 255 ]
Example: tp_sprout_rVGCC6WdrNxjCf6JpCHP
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/tracking-plans/{trackingPlanId}
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.trackingPlans.getTrackingPlan('tp_sprout_rVGCC6WdrNxjCf6JpCHP'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Update Tracking Plan

Updates a Tracking Plan.

• In order to successfully call this endpoint, the specified Workspace needs to have the Protocols feature enabled. Please reach out to your customer success manager for more information.

Config API omitted fields:

  • updateMask
Securitytoken
Request
path Parameters
trackingPlanId
required
string [ 1 .. 255 ]
Example: tp_sprout_rVGCC6WdrNxjCf6JpCHP
Request Body schema:
required
name
string (name)

The Tracking Plan's name.

Config API note: equal to displayName.

description
string (description)

The Tracking Plan's description.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

patch/tracking-plans/{trackingPlanId}
Request samples
{
  • "name": "Updated TP"
}
Response samples
{
  • "data": {
    }
}

List Rules from Tracking Plan

Lists Tracking Plan rules.

• In order to successfully call this endpoint, the specified Workspace needs to have the Protocols feature enabled. Please reach out to your customer success manager for more information.

The rate limit for this endpoint is 200 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
path Parameters
trackingPlanId
required
string [ 1 .. 255 ]
Example: tp_sprout_rVGCC6WdrNxjCf6JpCHP
query Parameters
required
object (PaginationInput)

Pagination options.

This parameter exists in v1.

Example: pagination=pagination.count=2
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/tracking-plans/{trackingPlanId}/rules
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.trackingPlans.listRulesFromTrackingPlan('tp_sprout_rVGCC6WdrNxjCf6JpCHP', 'pagination.count=2'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Remove Rules from Tracking Plan

Deletes Tracking Plan rules.

• In order to successfully call this endpoint, the specified Workspace needs to have the Protocols feature enabled. Please reach out to your customer success manager for more information.

Securitytoken
Request
path Parameters
trackingPlanId
required
string [ 1 .. 255 ]
Example: tp_sprout_rVGCC6WdrNxjCf6JpCHP
query Parameters
required
Array of objects (rules)

Rules to delete.

This parameter exists in v1.

Example: rules=rules.0.key=New%20Rule&rules.0.type=TRACK&rules.0.version=1
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/tracking-plans/{trackingPlanId}/rules
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(
    api.trackingPlans.removeRulesFromTrackingPlan(
      'tp_sprout_rVGCC6WdrNxjCf6JpCHP',
      'rules.0.key=New%20Rule&rules.0.type=TRACK&rules.0.version=1'
    )
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Replace Rules in Tracking Plan

Replaces Tracking Plan rules.

• In order to successfully call this endpoint, the specified Workspace needs to have the Protocols feature enabled. Please reach out to your customer success manager for more information.

Securitytoken
Request
path Parameters
trackingPlanId
required
string [ 1 .. 255 ]
Example: tp_sprout_rVGCC6WdrNxjCf6JpCHP
Request Body schema:
required
required
Array of objects (rules)

Rules to replace.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

put/tracking-plans/{trackingPlanId}/rules
Request samples
{
  • "rules": [
    ]
}
Response samples
{
  • "data": {
    }
}

Update Rules in Tracking Plan

Updates Tracking Plan rules.

• In order to successfully call this endpoint, the specified Workspace needs to have the Protocols feature enabled. Please reach out to your customer success manager for more information.

Securitytoken
Request
path Parameters
trackingPlanId
required
string [ 1 .. 255 ]
Example: tp_sprout_rVGCC6WdrNxjCf6JpCHP
Request Body schema:
required
required
Array of objects (rules)

Rules to update or insert.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

patch/tracking-plans/{trackingPlanId}/rules
Request samples
{
  • "rules": [
    ]
}
Response samples
{
  • "data": {
    }
}