# Read Tag Statistics Over Time

Reads tag counts over time for up to ten manual or automatic tags, grouped by hour, day, month or year. The only statistics tool scoped to a period; the others report lifetime totals. Counts only current holders, dated by their latest tagging; removed tags do not appear. Empty periods are omitted. This is not a tagging history; use get-contact-history for one contact. Requests exceeding 2000 periods are refused.

## 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"
                }
              }
            }
          }
        }
      }
    }
  }
}
```