> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forestreet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User Activities

> Get the activities of a user during a specific time period, up to 180 days.

This endpoint queries the studies accessible to a given user, checks for either:

* studies that were **created in** the given time period, or
* studies that had additional **discoveries run** in the given time period, or
* studies that were **last published** in the given time period,

and returns a object including the

* **Team** and **Market Collection** ID that allows the user's access to the market,
* the **Market ID**,
* the **Market Title**,
* the **draft/published status** of the market,
* the **creation** and **publish date** of the market,
* the **number of companies** in the market by their review and published status, and
* the **discovery history** of the market including timestamps for each.

This endpoints serves as a starting point for a management user to generate statistics of a user's usage and utilisation
pattern of the platform.

### Query

<ParamField query="uuid" type="string">
  The UUID of the user whose activities you want to retrieve.

  <Note>Only one of the `uuid` or the `email` parameter can be provided at a time.</Note>
</ParamField>

<ParamField query="email" type="string">
  The email of the user whose activities you want to retrieve.

  <Tip>
    The email must be case-insensitively identical to the email associated with the account; in the case of SSO users,
    this will be the email provided as the `email` SAML attribute.

    <br />

    <br />

    Ensure you include all the necessary components for a strict match, such as any suffixes in the
    `first.last+suffix@your.domain` convention.
  </Tip>

  <Note>Only one of the `uuid` or the `email` parameter can be provided at a time.</Note>
</ParamField>

<ParamField query="days" type="number">
  The number of days to look back for the activities.

  <Note>The maximum number of days is 180.<br /><br />Only one of `days` or `start` and `end` pair can be provided at a time.</Note>
</ParamField>

<ParamField query="start" type="string">
  The start date of the period to look for the activities.

  <Note>The date must be in the `YYYY-MM-DD` ISO 8601 format.<br /><br />Only one of `days` or `start` and `end` pair can be provided at a time.</Note>
</ParamField>

<ParamField query="end" type="string">
  The end date of the period to look for the activities.

  If not provided, but `start` is provided, the end date will be set to the current date.

  <Note>
    The date must be in the `YYYY-MM-DD` ISO 8601 format.

    <br />

    <br />

    Only one of `days` or `start` and `end` pair can be provided at a time.
  </Note>
</ParamField>

### Response

<ResponseField name="user" type="object">
  The user object containing the `userId` and `email` of the user.

  <Accordion title="Managed User Object" defaultOpen>
    <ResponseField name="userId" type="string">
      The UUID of the user.
    </ResponseField>

    <ResponseField name="email" type="string">
      The email of the user.
    </ResponseField>
  </Accordion>
</ResponseField>

<ResponseField name="createdAt" type="string">
  The time at which this report was generated.

  This will be in the ISO 8601 format, i.e. `YYYY-MM-DDTHH:MM:SS.sssZ`, in UTC timezone.
</ResponseField>

<ResponseField name="capturePeriod" type="object">
  The period for which the activities were captured.

  This simply mirrors the query parameters provided.
</ResponseField>

<ResponseField name="markets" type="array">
  The list of markets that the user interacted with during the capture period.
  Markets should be unique by their `marketId`.

  Each of them contains the following fields:

  <Accordion title="Market Object" defaultOpen>
    This object contains the details of a single market.

    <ResponseField name="teamId" type="number">
      The ID of the team that the user belongs to, which allowed the user access to this market.
    </ResponseField>

    <ResponseField name="collectionId" type="number">
      The ID of the market collection that the user belongs to, which allowed the user access to this market.

      This is typically attached to the team above.
    </ResponseField>

    <ResponseField name="marketId" type="number">
      The ID of the market.
    </ResponseField>

    <ResponseField name="marketTitle" type="string">
      The title of the market.
    </ResponseField>

    <ResponseField name="marketStatus" type="string">
      The status of the market.

      This can be either `draft` or `published`:

      * `draft`: Discoveries had been run, but the market has not been published, and the companies had not been enriched. `marketPublishedDate` will be `null`.
      * `published`: The market has been published, and the companies had been enriched; `marketPublishedDate` will be set.
    </ResponseField>

    <ResponseField name="marketCreationDate" type="string">
      The time at which the market was created.

      This will be in the ISO 8601 format, i.e. `YYYY-MM-DDTHH:MM:SS.sssZ`, in UTC timezone.

      Typically the market is created just before the first Discovery is run, in order to receive
      the companies found in the Discovery. The Discoveries will have a different timestamp of their own.
    </ResponseField>

    <ResponseField name="marketPublishedDate" type="string" optional>
      The time at which the market was published.

      This will be in the ISO 8601 format, i.e. `YYYY-MM-DDTHH:MM:SS.sssZ`, in UTC timezone.

      This will be `null` if the market is still in draft status.
    </ResponseField>

    <ResponseField name="domainCounts" type="object">
      The number of companies in the market by their review and published status.

      This is a overview of the companies in the market - this is not affected by
      the filters applied to the request.

      <Accordion title="Domain Counts Object">
        The `domainCounts` object contains a number of fields, each representing
        a different status of the companies in the market, mapped to an status object
        as follows:

        <Accordion title="Status Object">
          <ResponseField name="count" type="number">
            The total number of companies in the market with this status.
          </ResponseField>

          <ResponseField name="lastOperation" type="string">
            The time of the last operation that added any company to this status.
          </ResponseField>
        </Accordion>

        The fields are as follows:

        <ResponseField name="include" type="object">
          The total number of companies included in the market currently.

          This does NOT include starred companies.
        </ResponseField>

        <ResponseField name="exclude" type="object" optional>
          The total number of companies excluded from the market currently.
        </ResponseField>

        <ResponseField name="unreviewed" type="object" optional>
          The total number of companies yet unreviewed in the market currently.
        </ResponseField>

        <ResponseField name="starred" type="object" optional>
          The total number of companies starred in the market currently.

          This implies that the companies were included.
        </ResponseField>

        <ResponseField name="published" type="object" optional>
          The total number of companies enriched in last market Publish event.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="discoveryHistory" type="array">
      The history of the discoveries run in the market.

      Each of them contains the following fields:

      <Accordion title="Discovery History Object" defaultOpen>
        <ResponseField name="user" type="object">
          The user who ran the discovery.

          This is the user who had access to the market, and ran the discovery.

          <Accordion title="Discovery User Object" defaultOpen>
            <ResponseField name="userId" type="string">
              The UUID of the user.
            </ResponseField>

            <ResponseField name="studyUserGroupId" type="number">
              The ID of the user group that the user belongs to, which allowed the user access to this market.

              <Tip>This is the same as Team ID; this is the old nomenclature for backward compatibility.</Tip>
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="marketRole" type="string">
          The role of the user in the market.

          Possible values are:

          * `"manufacturer"` - physical product manufacturing, e.g. a car manufacturer
          * `"distributor"` - physical product distribution, e.g. a car dealership
          * `"service provider"` - contractor or provider of pre-defined services, e.g. a car repair shop
          * `"consultant"` - consultants or advisers not themselves participating in the market, but offers advice to those who do, e.g. a motor regulatory consultant

          This is a hint to the discovery process and does not guarantee that all returned
          companies will fit this role. If insufficient companies are found, the search will be
          broadened to include other roles.
        </ResponseField>

        <ResponseField name="seedDomains" type="array" optional>
          The seed domains used in the discovery.

          These domains are guaranteed to be included in the results of the discovery, and do not count
          towards the total number of companies found.
        </ResponseField>

        <ResponseField name="locations" type="object[]">
          The locations of the user in the market.

          This is an array of objects, each representing a location of the user in the market.

          <Accordion title="Location Object" defaultOpen>
            A location object representing a location to perform a search in.

            If the object is empty, it means a global search is to be performed.

            <ResponseField name="country" type="string" optional>
              The country code of the location.

              This is the ISO 3166-1 alpha-2 country code.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="count" type="number">
          The number of companies desired in the discovery.

          <Tip>This is not the number of companies found.</Tip>
        </ResponseField>

        <ResponseField name="constraints" type="object" optional>
          The constraints applied in the discovery.

          This is an object containing the constraints applied in the discovery.

          <Note>This is currently an internal object not designed for external consumption. Do not infer any schema from it, as it might change without notice.</Note>
        </ResponseField>

        <ResponseField name="performSearch" type="boolean">
          Whether this is a discovery that involves a market search.

          If the user manually added a company, this will be `false`.
        </ResponseField>

        <ResponseField name="createdAt" type="string">
          The time at which the discovery was run.

          This will be in the ISO 8601 format, i.e. `YYYY-MM-DDTHH:MM:SS.sssZ`, in UTC timezone.
        </ResponseField>

        <ResponseField name="userKeywords" type="array">
          The keywords used by the user in the discovery.
        </ResponseField>
      </Accordion>
    </ResponseField>
  </Accordion>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
      "user": {
          "userId": "960e2b94-781d-4ffc-8711-385d5f06b4b3",
          "email": "john@doe.com"
      },
      "createdAt": "2025-03-19T05:13:00.995Z",
      "capturePeriod": {
          "days": 30
      },
      "markets": [
          {
              "teamId": 141,
              "collectionId": 546,
              "marketId": 5553,
              "marketTitle": "Flexible Packaging in Mexico",
              "marketStatus": "published",
              "marketCreationDate": "2025-02-18T12:16:58.000Z",
              "marketPublishedDate": "2025-02-18T14:50:54.000Z",
              "domainCounts": {
                  "include": {
                      "count": 19,
                      "lastOperation": "2025-02-18T14:50:23.000Z"
                  },
                  "unreviewed": {
                      "count": 31,
                      "lastOperation": null
                  },
                  "published": {
                      "count": 19,
                      "lastOperation": "2025-02-18T14:50:57.257Z"
                  }
              },
              "discoveryHistory": [
                  {
                      "user": {
                          "userId": "637d78e5-9fbb-4e61-818f-0b13f7f6a345",
                          "studyUserGroupId": 141
                      },
                      "marketRole": "manufacturer",
                      "seedDomains": [],
                      "locations": [
                          {
                              "country": "MX"
                          }
                      ],
                      "count": 50,
                      "constraints": null,
                      "performSearch": true,
                      "createdAt": "2025-02-18T12:16:58.725Z",
                      "userKeywords": [
                          "laminated film bags"
                      ]
                  }
              ]
          },
          {
              "teamId": 141,
              "collectionId": 546,
              "marketId": 5568,
              "marketTitle": "UK Logistics",
              "marketStatus": "draft",
              "marketCreationDate": "2025-02-28T00:04:08.000Z",
              "marketPublishedDate": null,
              "domainCounts": {
                  "unreviewed": {
                      "count": 50,
                      "lastOperation": null
                  }
              },
              "discoveryHistory": [
                  {
                      "user": {
                          "userId": "637d78e5-9fbb-4e61-818f-0b13f7f6a345",
                          "studyUserGroupId": 141
                      },
                      "marketRole": "service provider",
                      "seedDomains": [],
                      "locations": [
                          {
                              "country": "GB"
                          }
                      ],
                      "count": 50,
                      "constraints": null,
                      "performSearch": true,
                      "createdAt": "2025-02-28T00:04:08.601Z",
                      "userKeywords": [
                          "security scanning",
                          "heathrow"
                      ]
                  }
              ]
          },
          {
              "teamId": 141,
              "collectionId": 546,
              "marketId": 5569,
              "marketTitle": "Cardboard Boxes",
              "marketStatus": "published",
              "marketCreationDate": "2025-03-04T18:07:24.000Z",
              "marketPublishedDate": "2025-03-04T18:25:09.000Z",
              "domainCounts": {
                  "include": {
                      "count": 2,
                      "lastOperation": "2025-03-04T18:24:55.000Z"
                  },
                  "unreviewed": {
                      "count": 48,
                      "lastOperation": null
                  },
                  "published": {
                      "count": 2,
                      "lastOperation": "2025-03-04T18:25:10.615Z"
                  }
              },
              "discoveryHistory": [
                  {
                      "user": {
                          "userId": "637d78e5-9fbb-4e61-818f-0b13f7f6a345",
                          "studyUserGroupId": 141
                      },
                      "marketRole": "manufacturer",
                      "seedDomains": [],
                      "locations": [{}],
                      "count": 50,
                      "constraints": null,
                      "performSearch": true,
                      "createdAt": "2025-03-04T18:07:24.846Z",
                      "userKeywords": []
                  }
              ]
          },
          {
              "teamId": 141,
              "collectionId": 546,
              "marketId": 5570,
              "marketTitle": "Cardboard Boxes in Europe",
              "marketStatus": "published",
              "marketCreationDate": "2025-03-04T18:07:46.000Z",
              "marketPublishedDate": "2025-03-04T18:24:41.000Z",
              "domainCounts": {
                  "unreviewed": {
                      "count": 48,
                      "lastOperation": null
                  },
                  "include": {
                      "count": 2,
                      "lastOperation": "2025-03-04T18:24:18.000Z"
                  },
                  "published": {
                      "count": 2,
                      "lastOperation": "2025-03-04T18:24:44.978Z"
                  }
              },
              "discoveryHistory": [
                  {
                      "user": {
                          "userId": "637d78e5-9fbb-4e61-818f-0b13f7f6a345",
                          "studyUserGroupId": 141
                      },
                      "marketRole": "manufacturer",
                      "seedDomains": [],
                      "locations": [
                          {
                              "country": "FR"
                          },
                          {
                              "country": "DE"
                          },
                          {
                              "country": "IT"
                          },
                          {
                              "country": "ES"
                          },
                          {
                              "country": "GB"
                          }
                      ],
                      "count": 50,
                      "constraints": null,
                      "performSearch": true,
                      "createdAt": "2025-03-04T18:07:46.728Z",
                      "userKeywords": []
                  }
              ]
          }
      ]
  }
  ```
</ResponseExample>