# Travel Data

Create travel trip data and activities for reporting and analytics, and read back, or delete,
what SQUAKE stored.

`POST /v2/travel-data` ingests trips and returns their emissions. The trip endpoints
(`/v2/travel-data/trips`) then serve the stored records: a trip carries its own attributes and
the IDs of its activities, and each activity carries its traveler and every calculation persisted
for it — including the ones from additional methodologies, which the flat `items` array of a
submission does not report.

To ingest travel data you need to have it enabled for your account — please contact us. Until
then, `POST /v2/travel-data` and the CSV imports respond with `404` and error code
`travel_data_not_found`. On the read endpoints that same response covers every miss: a trip that
does not exist and a trip you cannot access are deliberately indistinguishable.


## Create Travel Data Items

 - [POST /v2/travel-data](https://docs-v2.squake.earth/docs/openapi/travel-data/post-v2-travel-data.md): Accepts trip records with nested activities for travel data ingestion.

 A single request may contain a maximum of  in total across all trips.
For larger data sets, split your payload into batches of up to 50 activities and send each batch as a separate request.
Requests exceeding this limit are rejected with a  error before any data is persisted.

If an activity omits , SQUAKE selects the client's configured default methodology for that activity type.
Pass  only when you want to override that default for a specific activity.
 , , , and .

 Both trips and individual activities accept  and .
Use activity-level values to attribute spend to a specific leg; they take precedence over trip-level values
in activity-based reporting. When  is present,  must be a positive integer.
The API does not accept .

 alongside the flat  array, the response returns a 
array with the ID of every trip this request persisted and the IDs of the activities written
under it. Store those IDs to read, or delete, the stored records later via

— or address a trip by your own  instead. A  entry reports the trip's
identity only; a trip read returns those same fields plus the trip as you described it (name,
purpose, status, dates, booking provider, amount, cost center).

 pass an optional root-level  (a client  as
returned by )
to store this travel data under a descendant client. Submitting data for another client must be
enabled for your account (contact us); omitting  preserves the existing behavior of
ingesting for the authenticated client. Note that CSV imports () do not
accept .

  activities accept the same methodology-specific fields as the corresponding
 flight schemas, including  for multi-leg itineraries (a hyphen-separated airport chain,
e.g. ) as an alternative to /. Exactly one of  or the /
pair must be provided;  only applies to  activities.


## List Travel Data Trips

 - [GET /v2/travel-data/trips](https://docs-v2.squake.earth/docs/openapi/travel-data/get-v2-travel-data-trips.md): Returns the trips stored for the authenticated client, most recently ingested first. Trips
from every source are listed — API submissions, CSV imports and TMC integrations alike.

Each trip is returned in full: the identity fields a submission echoes back (,
, , , ) plus the trip as you
described it on ingestion — , , , ,
, , ,  and the nested .

What a trip does  carry is its activities: only their IDs. Read an activity, its
traveler, its calculations and its audit references from
.

 results are paginated with the  and  query parameters, and the
pagination metadata is returned in the response headers (, ,
, , and an RFC 8288  header).

 if submitting on behalf of other clients is enabled for your account, this
lists the trips of the authenticated client and all of its descendants. Otherwise only your
own trips are returned — never a parent's, a sibling's, or an unrelated client's. A client
with no stored trips gets an empty array.


## Retrieve a Travel Data Trip

 - [GET /v2/travel-data/trips/{id}](https://docs-v2.squake.earth/docs/openapi/travel-data/get-v2-travel-data-trips-id.md): Returns a single stored trip, addressed either by its SQUAKE  or by your own
. The response is the same shape the trip list returns: the identity fields a
submission echoes back plus the trip as you described it on ingestion — name, purpose, status,
dates, booking provider, amount and the nested .

The trip carries the IDs of its activities, not the activities themselves — read those from
.

A trip you cannot access is indistinguishable from one that does not exist: both respond with
 and error code .


## Delete a Travel Data Trip

 - [DELETE /v2/travel-data/trips/{id}](https://docs-v2.squake.earth/docs/openapi/travel-data/delete-v2-travel-data-trips-id.md): Deletes a trip and everything hanging off it: all of its activities — routing legs
included — and their calculations. Responds with  and an empty body.

 They are an immutable record of what was calculated, so deleting a
trip does not remove the audit logs its calculations produced.

 Dashboards and reporting views are refreshed periodically, so a
deleted trip can still appear in them until the next refresh.

This cannot be undone — re-submit the trip to  to restore it, which
recalculates its emissions and creates new IDs.

A trip you cannot access responds with  and error code , and
nothing is deleted.


## List the Activities of a Travel Data Trip

 - [GET /v2/travel-data/trips/{trip_id}/activities](https://docs-v2.squake.earth/docs/openapi/travel-data/get-v2-travel-data-trips-trip-id-activities.md): Returns every activity of a trip, in ingestion order, each with its traveler and the
calculations persisted for it. A trip is a single booking, so the list is bounded and returned
in full — it is not paginated.

This is where additional methodologies become visible: the  array of
 only reports the primary methodology of each activity, while an
activity here carries one calculation per methodology configured for its type.

  and  are returned for
,  and  but not for ;  only for  and . A key
the type cannot have is omitted rather than returned as , so read  first.
 is always present, and is  for an activity submitted without one.

Individual legs of a  flight are not listed — the routed activity carries the
itinerary total.

A trip you cannot access responds with  and error code .


## Retrieve an Activity of a Travel Data Trip

 - [GET /v2/travel-data/trips/{trip_id}/activities/{activity_id}](https://docs-v2.squake.earth/docs/openapi/travel-data/get-v2-travel-data-trips-trip-id-activities-activity-id.md): Returns a single activity of a trip with its traveler and the calculations persisted for it.
Activities are always addressed through their trip.

As in the list, the key set depends on the activity : / are absent
for a  stay, and  is only returned for  and .

An activity of another trip, a routing leg, and an ID that does not exist all respond with
 and error code .