# Get usage time series

> For the complete documentation index, see [llms.txt](/docs/llms.txt).

POST https://admin-api.alchemy.com/v1/usage/time-series

Retrieves daily usage over time with optional product, metric, filter, and dimension controls.

Reference: https://www.alchemy.com/docs/tutorials/tools/admin-api/usage-api-endpoints/get-usage-time-series

## Headers

| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | Yes | Bearer authentication token |

## Code Examples

### cURL

```bash
curl --request POST \
  --url https://admin-api.alchemy.com/v1/usage/time-series \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "startTime": "string",
  "endTime": "string",
  "products": [
    "string"
  ],
  "metrics": [
    "amount"
  ],
  "filters": {
    "appIds": [
      "string"
    ],
    "networks": [
      "string"
    ],
    "methods": [
      "string"
    ],
    "requestTypes": [
      "string"
    ]
  },
  "groupBy": [
    "requestType"
  ],
  "granularity": "hour"
}'
```

### JavaScript

```javascript
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    startTime: 'string',
    endTime: 'string',
    products: ['string'],
    metrics: ['amount'],
    filters: {
      appIds: ['string'],
      networks: ['string'],
      methods: ['string'],
      requestTypes: ['string']
    },
    groupBy: ['requestType'],
    granularity: 'hour'
  })
};

fetch('https://admin-api.alchemy.com/v1/usage/time-series', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://admin-api.alchemy.com/v1/usage/time-series"

payload = {
    "startTime": "string",
    "endTime": "string",
    "products": ["string"],
    "metrics": ["amount"],
    "filters": {
        "appIds": ["string"],
        "networks": ["string"],
        "methods": ["string"],
        "requestTypes": ["string"]
    },
    "groupBy": ["requestType"],
    "granularity": "hour"
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

### Go

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://admin-api.alchemy.com/v1/usage/time-series"

	payload := strings.NewReader("{\n  \"startTime\": \"string\",\n  \"endTime\": \"string\",\n  \"products\": [\n    \"string\"\n  ],\n  \"metrics\": [\n    \"amount\"\n  ],\n  \"filters\": {\n    \"appIds\": [\n      \"string\"\n    ],\n    \"networks\": [\n      \"string\"\n    ],\n    \"methods\": [\n      \"string\"\n    ],\n    \"requestTypes\": [\n      \"string\"\n    ]\n  },\n  \"groupBy\": [\n    \"requestType\"\n  ],\n  \"granularity\": \"hour\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

### Java

```java
HttpResponse<String> response = Unirest.post("https://admin-api.alchemy.com/v1/usage/time-series")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"startTime\": \"string\",\n  \"endTime\": \"string\",\n  \"products\": [\n    \"string\"\n  ],\n  \"metrics\": [\n    \"amount\"\n  ],\n  \"filters\": {\n    \"appIds\": [\n      \"string\"\n    ],\n    \"networks\": [\n      \"string\"\n    ],\n    \"methods\": [\n      \"string\"\n    ],\n    \"requestTypes\": [\n      \"string\"\n    ]\n  },\n  \"groupBy\": [\n    \"requestType\"\n  ],\n  \"granularity\": \"hour\"\n}")
  .asString();
```

### C#

```csharp
using RestSharp;


var options = new RestClientOptions("https://admin-api.alchemy.com/v1/usage/time-series");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
request.AddJsonBody("{\n  \"startTime\": \"string\",\n  \"endTime\": \"string\",\n  \"products\": [\n    \"string\"\n  ],\n  \"metrics\": [\n    \"amount\"\n  ],\n  \"filters\": {\n    \"appIds\": [\n      \"string\"\n    ],\n    \"networks\": [\n      \"string\"\n    ],\n    \"methods\": [\n      \"string\"\n    ],\n    \"requestTypes\": [\n      \"string\"\n    ]\n  },\n  \"groupBy\": [\n    \"requestType\"\n  ],\n  \"granularity\": \"hour\"\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

```


## Operation Specification

```yaml
path: /v1/usage/time-series
method: POST
operation:
  operationId: GetUsageTimeSeries
  responses:
    '200':
      description: Retrieved usage time series successfully
      content:
        application/json:
          schema:
            description: |-
              Standard API response wrapper.
              All API responses are wrapped in this format for consistency.
            properties:
              data:
                properties:
                  query:
                    properties:
                      startTime:
                        type: string
                      endTime:
                        type: string
                      granularity:
                        enum:
                          - hour
                          - day
                        type: string
                      products:
                        items:
                          type: string
                        type: array
                      metrics:
                        items:
                          enum:
                            - amount
                            - usd
                          type: string
                        type: array
                      filters:
                        properties:
                          appIds:
                            items:
                              type: string
                            type: array
                          networks:
                            items:
                              type: string
                            type: array
                          methods:
                            items:
                              type: string
                            type: array
                          requestTypes:
                            items:
                              type: string
                            type: array
                        type: object
                        additionalProperties: false
                      groupBy:
                        items:
                          enum:
                            - requestType
                            - app
                            - network
                            - method
                          type: string
                        type: array
                    required:
                      - startTime
                      - endTime
                      - granularity
                      - products
                      - metrics
                      - groupBy
                    type: object
                    additionalProperties: false
                  freshness:
                    properties:
                      dataThrough:
                        type: string
                      containsPartialToday:
                        type: boolean
                      updateCadence:
                        enum:
                          - minute
                        type: string
                    required:
                      - dataThrough
                      - containsPartialToday
                      - updateCadence
                    type: object
                    additionalProperties: false
                  data:
                    items:
                      properties:
                        startTime:
                          type: string
                        endTime:
                          type: string
                        isPartial:
                          type: boolean
                        dimensions:
                          properties:
                            requestType:
                              type: string
                            app:
                              type: string
                            network:
                              type: string
                            method:
                              type: string
                          type: object
                          additionalProperties: false
                        amount:
                          type: string
                        unit:
                          type: string
                        usd:
                          type: string
                      required:
                        - startTime
                        - endTime
                        - isPartial
                        - dimensions
                      type: object
                      additionalProperties: false
                    type: array
                required:
                  - query
                  - freshness
                  - data
                type: object
                additionalProperties: false
            required:
              - data
            type: object
            additionalProperties: false
    '400':
      description: Invalid input
      content:
        application/json:
          schema:
            description: |-
              Standard error response wrapper.
              All error responses are wrapped in this format for consistency.
            properties:
              error:
                properties:
                  message:
                    type: string
                  code:
                    anyOf:
                      - type: integer
                        format: int32
                      - enum:
                          - 500
                          - 400
                          - 401
                          - 403
                          - 404
                          - 200
                          - 201
                          - 1000
                        type: number
                  status:
                    type: integer
                    format: int32
                  context:
                    description: Additional information about the error specific to the endpoint.
                    properties: {}
                    type: object
                    additionalProperties: {}
                required:
                  - message
                  - code
                  - status
                type: object
                additionalProperties: false
            required:
              - error
            type: object
            additionalProperties: false
          examples:
            Example 1:
              value:
                error:
                  code: 400
                  status: 400
                  message: Invalid input
    '401':
      description: Requires authentication
      content:
        application/json:
          schema:
            description: |-
              Standard error response wrapper.
              All error responses are wrapped in this format for consistency.
            properties:
              error:
                properties:
                  message:
                    type: string
                  code:
                    anyOf:
                      - type: integer
                        format: int32
                      - enum:
                          - 500
                          - 400
                          - 401
                          - 403
                          - 404
                          - 200
                          - 201
                          - 1000
                        type: number
                  status:
                    type: integer
                    format: int32
                  context:
                    description: Additional information about the error specific to the endpoint.
                    properties: {}
                    type: object
                    additionalProperties: {}
                required:
                  - message
                  - code
                  - status
                type: object
                additionalProperties: false
            required:
              - error
            type: object
            additionalProperties: false
          examples:
            Example 1:
              value:
                error:
                  code: 401
                  status: 401
                  message: Requires authentication
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            description: |-
              Standard error response wrapper.
              All error responses are wrapped in this format for consistency.
            properties:
              error:
                properties:
                  message:
                    type: string
                  code:
                    anyOf:
                      - type: integer
                        format: int32
                      - enum:
                          - 500
                          - 400
                          - 401
                          - 403
                          - 404
                          - 200
                          - 201
                          - 1000
                        type: number
                  status:
                    type: integer
                    format: int32
                  context:
                    description: Additional information about the error specific to the endpoint.
                    properties: {}
                    type: object
                    additionalProperties: {}
                required:
                  - message
                  - code
                  - status
                type: object
                additionalProperties: false
            required:
              - error
            type: object
            additionalProperties: false
          examples:
            Example 1:
              value:
                error:
                  code: 403
                  status: 403
                  message: Forbidden
    '404':
      description: Not found
      content:
        application/json:
          schema:
            description: |-
              Standard error response wrapper.
              All error responses are wrapped in this format for consistency.
            properties:
              error:
                properties:
                  message:
                    type: string
                  code:
                    anyOf:
                      - type: integer
                        format: int32
                      - enum:
                          - 500
                          - 400
                          - 401
                          - 403
                          - 404
                          - 200
                          - 201
                          - 1000
                        type: number
                  status:
                    type: integer
                    format: int32
                  context:
                    description: Additional information about the error specific to the endpoint.
                    properties: {}
                    type: object
                    additionalProperties: {}
                required:
                  - message
                  - code
                  - status
                type: object
                additionalProperties: false
            required:
              - error
            type: object
            additionalProperties: false
          examples:
            Example 1:
              value:
                error:
                  code: 404
                  status: 404
                  message: Path not found
  description: Retrieves daily usage over time with optional product, metric, filter, and dimension controls.
  summary: Get usage time series
  security:
    - user_auth:
        - viewer
        - developer
        - admin
  parameters: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          properties:
            startTime:
              type: string
            endTime:
              type: string
              description: Defaults to now when omitted.
            products:
              items:
                type: string
              type: array
              description: BillingProduct enum names.
              example:
                - SUPERNODE_CU
            metrics:
              items:
                enum:
                  - amount
                  - usd
                type: string
              type: array
            filters:
              properties:
                appIds:
                  items:
                    type: string
                  type: array
                networks:
                  items:
                    type: string
                  type: array
                methods:
                  items:
                    type: string
                  type: array
                requestTypes:
                  items:
                    type: string
                  type: array
              type: object
              additionalProperties: false
            groupBy:
              items:
                enum:
                  - requestType
                  - app
                  - network
                  - method
                type: string
              type: array
            granularity:
              enum:
                - hour
                - day
              type: string
          required:
            - startTime
          type: object
          additionalProperties: false
```