Browse API documentation
API documentation

Milestones

Annotate your reports with important dates.

Search API documentation
    v1

    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
}