API reference
Browse API documentation
API reference

Milestones

Annotate your reports with important dates.

List milestones#

GET/sites/{site_id}/milestones

Return a list of all milestones this site owns. Milestones are sorted by created_at ascending to allow you to paginate with ease.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS

Query parameters

limitintegeroptional
A limit on the number of objects to be returned, between 1 and 100.
Default 10
starting_afterstringoptional
A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For example, if you make a list request and receive 10 objects ending with obj_foo, your subsequent call can include starting_after=obj_foo to fetch the next page.
ending_beforestringoptional
A cursor for use in pagination, working in the opposite direction to starting_after. ending_before is an object ID that defines your place in the list.

Returns

A list of milestone objects.

GET
curl "https://api.usefathom.com/v1/sites/CDBUGS/milestones" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
Response
{
    "object": "list",
    "url": "/api/v1/CDBUGS/milestones",
    "has_more": false,
    "data": [
        {
            "id": "ddc9cdff-ab83-41fa-96c6-dfb276a862e7",
            "object": "milestone",
            "name": "Website Redesign Launch",
            "milestone_date": "2024-01-15 00:00:00",
            "created_at": "2024-01-10 12:00:00",
            "updated_at": "2024-01-10 12:00:00"
        },
        {
            "id": "7c3a1b29-5d64-4e0a-b1f2-9a8c7e6d5f43",
            "object": "milestone",
            "name": "Marketing Campaign Start",
            "milestone_date": "2024-02-01 00:00:00",
            "created_at": "2024-01-20 09:30:00",
            "updated_at": "2024-01-20 09:30:00"
        }
    ]
}

Get milestone#

GET/sites/{site_id}/milestones/{milestone_id}

Return a single milestone.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS
milestone_idstringrequired
The id (UUID) of the milestone you wish to retrieve.

Returns

A milestone object.

GET
curl "https://api.usefathom.com/v1/sites/CDBUGS/milestones/ddc9cdff-ab83-41fa-96c6-dfb276a862e7" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
Response
{
    "id": "ddc9cdff-ab83-41fa-96c6-dfb276a862e7",
    "object": "milestone",
    "name": "Website Redesign Launch",
    "milestone_date": "2024-01-15 00:00:00",
    "created_at": "2024-01-10 12:00:00",
    "updated_at": "2024-01-10 12:00:00"
}

Create milestone#

POST/sites/{site_id}/milestones

Create a milestone. Returns HTTP 201 Created on success.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS

Body parameters

namestringrequired
The name of the milestone (up to 30 characters).
milestone_datestringrequired
The date of the milestone in YYYY-MM-DD format.

Returns

A milestone object.

POST
curl -X POST "https://api.usefathom.com/v1/sites/CDBUGS/milestones" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Website Redesign Launch",
    "milestone_date": "2024-01-15"
  }'
Response201
{
    "id": "ddc9cdff-ab83-41fa-96c6-dfb276a862e7",
    "object": "milestone",
    "name": "Website Redesign Launch",
    "milestone_date": "2024-01-15 00:00:00",
    "created_at": "2024-01-10 12:00:00",
    "updated_at": "2024-01-10 12:00:00"
}

Update milestone#

POST/sites/{site_id}/milestones/{milestone_id}

Update a milestone. Both name and milestone_date are required.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS
milestone_idstringrequired
The id (UUID) of the milestone you wish to update.

Body parameters

namestringrequired
The name of the milestone (up to 30 characters).
milestone_datestringrequired
The date of the milestone in YYYY-MM-DD format.

Returns

A milestone object.

POST
curl -X POST "https://api.usefathom.com/v1/sites/CDBUGS/milestones/ddc9cdff-ab83-41fa-96c6-dfb276a862e7" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Website Redesign Launch v2",
    "milestone_date": "2024-01-20"
  }'
Response
{
    "id": "ddc9cdff-ab83-41fa-96c6-dfb276a862e7",
    "object": "milestone",
    "name": "Website Redesign Launch v2",
    "milestone_date": "2024-01-20 00:00:00",
    "created_at": "2024-01-10 12:00:00",
    "updated_at": "2024-01-10 12:30:00"
}

Delete milestone#

DELETE/sites/{site_id}/milestones/{milestone_id}

Delete a milestone. Careful: you can't undo this, and neither can we.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS
milestone_idstringrequired
The id (UUID) of the milestone you wish to delete.

Returns

Returns a deleted object on success. Otherwise, this call returns an error.

DELETE
curl -X DELETE "https://api.usefathom.com/v1/sites/CDBUGS/milestones/ddc9cdff-ab83-41fa-96c6-dfb276a862e7" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
Response
{
    "id": "ddc9cdff-ab83-41fa-96c6-dfb276a862e7",
    "object": "milestone",
    "deleted": true
}