Import a tracking plan from CSV

Sends a tracking-plan CSV as the request body and applies it to a new import branch.
This endpoint always imports into a branch and never writes to main directly.
Creating the branch publishes any pending changes on main's staging version
first, as creating a branch in the product does. When the import fails after
the branch was created (422 for invalid rows, 502 for a server failure), the
error payload includes details.branch so callers can inspect or delete the
branch. A duplicate branch_name returns 409 before anything is created.

post/v1/projects/{project_id}/tracking-plan/import

Authorizations

Authorizationstringrequired

http

Path parameters

project_idstringrequired

Amplitude project identifier, backed by the canonical app ID.

Example:12345
Constraints:pattern: ^[0-9]+$

Query parameters

branch_namestring

Optional name for the import branch, 1 to 256 characters. When omitted, the import uses import, or import-N if that name is taken. A name that already exists returns 409.

Constraints:min length: 1max length: 256

Body

text/csv
Other properties1
valuestring

Response

application/json
201· Import completed on an import branch.
dataobjectrequired
Show child attributes
objectstringrequired
Allowed values:tracking_plan_import
project_idstringrequired
branch_idstringrequired
branch_namestring
Constraints:nullable
current_version_idstring
Constraints:nullable
staging_version_idstring
Constraints:nullable
import_typestringrequired

Public import target type. events includes event, template, event-property, and template-property rows; user_properties includes user-property rows.

Allowed values:eventsuser_properties
event_countintegerrequired
template_countintegerrequired
user_property_countintegerrequired
breakdownobject

Per-type import counters. Units:

  • templates/events/user_properties: definition rows changed.
  • template_properties/event_properties created|updated:

property definition rows changed.

  • template_properties/event_properties unmapped: properties

removed from templates/events; the property definition is kept.

Constraints:nullable
templatesobject
createdintegerrequired
updatedintegerrequired
removedintegerrequired
template_propertiesobject
createdintegerrequired
updatedintegerrequired
unmappedintegerrequired
eventsobject
createdintegerrequired
updatedintegerrequired
removedintegerrequired
event_propertiesobject
createdintegerrequired
updatedintegerrequired
unmappedintegerrequired
user_propertiesobject
createdintegerrequired
updatedintegerrequired
removedintegerrequired
409· The requested branch_name already exists. Nothing was created; choose another name.
typestringrequired
Constraints:format: uri
titlestringrequired
statusintegerrequired
Constraints:min: 400max: 599
detailstring
Constraints:nullable
detailsobject
Constraints:nullable
instancestring
Constraints:format: urinullable
error_codestringrequired
retryablebooleanrequired
retry_after_secondsinteger
Constraints:nullablemin: 0
validation_errorsobject[]
Constraints:nullable
422· The CSV is not valid tracking-plan data. details.branch is present when the error was found after the import branch was created.
typestringrequired
Constraints:format: uri
titlestringrequired
statusintegerrequired
Constraints:min: 400max: 599
detailstring
Constraints:nullable
detailsobject
Constraints:nullable
Show child attributes
branchobject
idstringrequired
namestringrequired
instancestring
Constraints:format: urinullable
error_codestringrequired
retryablebooleanrequired
retry_after_secondsinteger
Constraints:nullablemin: 0
validation_errorsobject[]
Constraints:nullable
502· The import did not finish. Not retryable when details.branch is present (the branch was created) or when the connection was lost mid-import (the import may have started): a retry could create a second branch. List the project's branches to find the result. A 502 without details.branch that is marked retryable means the import was never started.
typestringrequired
Constraints:format: uri
titlestringrequired
statusintegerrequired
Constraints:min: 400max: 599
detailstring
Constraints:nullable
detailsobject
Constraints:nullable
Show child attributes
branchobject
idstringrequired
namestringrequired
instancestring
Constraints:format: urinullable
error_codestringrequired
retryablebooleanrequired
retry_after_secondsinteger
Constraints:nullablemin: 0
validation_errorsobject[]
Constraints:nullable
504· The import did not respond in time and may still complete. Not retryable: a retry may create a second branch. List the project's branches to find the result.
typestringrequired
Constraints:format: uri
titlestringrequired
statusintegerrequired
Constraints:min: 400max: 599
detailstring
Constraints:nullable
detailsobject
Constraints:nullable
instancestring
Constraints:format: urinullable
error_codestringrequired
retryablebooleanrequired
retry_after_secondsinteger
Constraints:nullablemin: 0
validation_errorsobject[]
Constraints:nullable

Was this helpful?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.