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:
application/json
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

200
404
422
429

{"data": {"status": "SUCCESS"
}
}

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

TypeScript
Java
Python
Go
curl

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

200
404
422
429

{"data": {"sources": [{"id": "qQEHquLrjRDN9j1ByrChyn",
"slug": "swift",
"name": "",
"workspaceId": "9aQ1Lj62S4bomZKLF4DPqW",
"enabled": true,
"writeKeys": ["bEj5MzDqCkHYRqreZgbPuH"
],
"metadata": {"id": "dZeHygTSD4",
"slug": "swift",
"name": "Apple",
"categories": ["Mobile"
],
"description": "The hassle-free way to add Segment analytics to your swift app (iOS, macOS, tvOS).",
"logos": {"default": "https://cdn.filepicker.io/api/file/qWgSP5cpS7eeW2voq13u",
"alt": "https://cdn.filepicker.io/api/file/qWgSP5cpS7eeW2voq13u",
"mark": "https://cdn.filepicker.io/api/file/CoPDNKCgSlyYVeQow6JW"
},
"options": [ ],
"isCloudEventSource": false
},
"settings": { },
"labels": [ ]
}
],
"pagination": {"current": "MA==",
"totalEntries": 1
}
}
}

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

TypeScript
Java
Python
Go
curl

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

200
404
422
429

{"data": {"status": "SUCCESS"
}
}

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:
application/json
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

200
404
422
429

{"data": {"trackingPlan": {"id": "tp_sprout_rVGCC6WdrNxjCf6JpCHP",
"name": "New TP",
"resourceSchemaId": "rs_1yVwS3zy60dONy9UhCyDqMmVvAE",
"slug": "",
"description": "",
"type": "LIVE",
"updatedAt": "2006-01-02T15:04:05.000Z",
"createdAt": "2006-01-02T15:04:05.000Z"
}
}
}

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

TypeScript
Java
Python
Go
curl

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

200
404
422
429

{"data": {"trackingPlans": [{"id": "tp_sprout_rVGCC6WdrNxjCf6JpCHP",
"name": "New TP",
"resourceSchemaId": "rs_1yVwS3zy60dONy9UhCyDqMmVvAE",
"slug": "",
"description": "",
"type": "LIVE",
"updatedAt": "2006-01-02T15:04:05.000Z",
"createdAt": "2006-01-02T15:04:05.000Z"
}
],
"pagination": {"current": "MA=="
}
}
}

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

TypeScript
Java
Python
Go
curl

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

200
404
422
429

{"data": {"status": "SUCCESS"
}
}

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

TypeScript
Java
Python
Go
curl

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

200
404
422
429

{"data": {"trackingPlan": {"id": "tp_sprout_rVGCC6WdrNxjCf6JpCHP",
"name": "New TP",
"resourceSchemaId": "rs_1yVwS3zy60dONy9UhCyDqMmVvAE",
"slug": "",
"description": "",
"type": "LIVE",
"updatedAt": "2006-01-02T15:04:05.000Z",
"createdAt": "2006-01-02T15:04:05.000Z"
}
}
}

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:
application/json
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

200
404
422
429

{"data": {"status": "SUCCESS"
}
}

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

TypeScript
Java
Python
Go
curl

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

200
404
422
429

{"data": {"rules": [{"key": "New Tracking Plan Rule",
"type": "TRACK",
"version": 1,
"jsonSchema": {"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {"context": {"type": "object"
},
"traits": {"type": "object"
},
"properties": {"type": "object"
}
}
},
"createdAt": "2006-01-02T15:04:05.000Z",
"updatedAt": "2006-01-02T15:04:05.000Z",
"deprecatedAt": "2006-01-02T15:04:05.000Z"
}
],
"pagination": {"current": "MA=="
}
}
}

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

TypeScript
Java
Python
Go
curl

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

200
404
422
429

{"data": {"status": "SUCCESS"
}
}

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:
application/json
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": [{"key": "New Replaced Rule",
"type": "TRACK",
"version": 1,
"jsonSchema": { }
}
]
}

Response samples

200
404
422
429

{"data": {"status": "SUCCESS"
}
}

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:
application/json
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": [{"key": "New Rule",
"type": "TRACK",
"version": 1,
"jsonSchema": { }
}
]
}

Response samples

200
404
422
429

{"data": {"status": "SUCCESS"
}
}

Tracking Plans

Migrate from the Config API

Add Source to Tracking Plan

path Parameters

Request Body schema: application/jsonapplication/vnd.segment.v1+jsonapplication/vnd.segment.v1beta+jsonapplication/vnd.segment.v1alpha+jsonapplication/jsonrequired

List Sources from Tracking Plan

path Parameters

query Parameters

Remove Source from Tracking Plan

path Parameters

query Parameters

Create Tracking Plan

Request Body schema: application/jsonapplication/vnd.segment.v1+jsonapplication/vnd.segment.v1beta+jsonapplication/vnd.segment.v1alpha+jsonapplication/jsonrequired

List Tracking Plans

query Parameters

Delete Tracking Plan

path Parameters

Get Tracking Plan

path Parameters

Update Tracking Plan

path Parameters

Request Body schema: application/jsonapplication/vnd.segment.v1+jsonapplication/vnd.segment.v1beta+jsonapplication/vnd.segment.v1alpha+jsonapplication/jsonrequired

List Rules from Tracking Plan

path Parameters

query Parameters

Remove Rules from Tracking Plan

path Parameters

query Parameters

Replace Rules in Tracking Plan

path Parameters

Request Body schema: application/jsonapplication/vnd.segment.v1+jsonapplication/vnd.segment.v1beta+jsonapplication/vnd.segment.v1alpha+jsonapplication/jsonrequired

Update Rules in Tracking Plan

path Parameters

Request Body schema: application/jsonapplication/vnd.segment.v1+jsonapplication/vnd.segment.v1beta+jsonapplication/vnd.segment.v1alpha+jsonapplication/jsonrequired

Request Body schema:
application/json
required

Request Body schema:
application/json
required

Request Body schema:
application/json
required

Request Body schema:
application/json
required

Request Body schema:
application/json
required