# Read Tag Statistics Over Time

Reads how many contacts were tagged with each of up to ten tags, per hour, day, month or year within a period. This is the only statistics tool that answers about a period: the others report lifetime totals. It counts the contacts that carry the tag now, each in the period they last got it. A tag that was removed again is not counted anywhere, and a contact tagged a second time moves to the period of the latest tagging. The statistics report in the app counts the same way. So this is not a log of every tagging that ever happened; for the full history of one contact use get-contact-history. A period in which nothing happened is left out rather than reported as zero, so absence means no taggings. Works with any tag the account has, manual or automatic. Refuses a request whose answer would carry more than 2000 periods: narrow the period or ask for a coarser granularity.

## Input schema:

```json
{
  "type": "object",
  "properties": {
    "tagIds": {
      "type": "array",
      "description": "IDs of the tags to count, one to ten; from search-tags or get-tag",
      "items": {
        "type": "integer",
        "minimum": 1
      },
      "minItems": 1,
      "maxItems": 10,
      "uniqueItems": true
    },
    "granularity": {
      "type": "string",
      "description": "Period each count covers: hour, day, month or year",
      "default": "day",
      "enum": [
        "hour",
        "day",
        "month",
        "year"
      ]
    },
    "from": {
      "type": [
        "null",
        "integer"
      ],
      "description": "Unix timestamp the period begins at; omit for the first tagging there is",
      "default": null,
      "minimum": 0
    },
    "to": {
      "type": [
        "null",
        "integer"
      ],
      "description": "Unix timestamp the period ends at; omit for now",
      "default": null,
      "minimum": 0
    },
    "accountId": {
      "type": [
        "null",
        "integer"
      ],
      "description": "User ID of the account; omit for the account the access token works in",
      "default": null,
      "minimum": 1
    }
  },
  "required": [
    "tagIds"
  ],
  "additionalProperties": false
}
```

## Output schema:

```json
{
  "type": "object",
  "required": [
    "granularity",
    "from",
    "to",
    "tags"
  ],
  "properties": {
    "granularity": {
      "type": "string"
    },
    "from": {
      "type": "integer"
    },
    "to": {
      "type": "integer"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "tagId",
          "name",
          "tagged",
          "periods"
        ],
        "properties": {
          "tagId": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "tagged": {
            "type": "integer"
          },
          "periods": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "period",
                "tagged"
              ],
              "properties": {
                "period": {
                  "type": "string"
                },
                "tagged": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    }
  }
}
```