---
title: Flow usage
url: https://www.tines.com/stories/docs/api/reporting/flow_usage/
updated: 2026-09-18T16:40:33+00:00
description: Returns the tenant's flow usage against its licensed flow limit, broken down by team. Each team shows how many flows its stories currently use and how many flows are allocated to it, so you can see how much of each team's allocation is in use. Teams without an allocation share the tenant's unallocated flows.
---

*[tines.com](https://www.tines.com/llms.txt) › [Docs](https://www.tines.com/stories/docs/llms.txt) › [Tines API](https://www.tines.com/stories/docs/api/llms.txt) › [Reporting](https://www.tines.com/llm/stories/docs/api/reporting.md)*

# Flow usage

*[View on tines.com](https://www.tines.com/stories/docs/api/reporting/flow_usage/)*

## Description

Returns the tenant's flow usage against its licensed flow limit, broken down by team. Each team shows how many flows its stories currently use and how many flows are allocated to it, so you can see how much of each team's allocation is in use. Teams without an allocation share the tenant's unallocated flows.

Flow counts are recalculated whenever a story changes rather than on each request.

Only tenant owners can call this endpoint, and it is only available to tenants on the flows pricing model. Tenants on other pricing models receive a `400` response.

## Request

HTTP Method: **GET**

| Query Parameter | Description                                                                             |
| --------------- | --------------------------------------------------------------------------------------- |
| per_page        | **Optional** Set the number of teams returned per page. Defaults to 20, maximum is 500. |
| page            | **Optional** The page number of results to fetch.                                       |

```bash
curl --proto '=https' --tlsv1.2 -X GET \
  https://<tenant-domain>/api/v1/reporting/flow_usage \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'
```

## Response

A successful response will return the tenant's overall flow usage and a paginated list of teams.

### Field description

| Parameter               | Description                                                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
| flows.used              | Flows currently used across the tenant                                                                             |
| flows.limit             | Licensed flow limit for the tenant                                                                                 |
| flows.allocated         | Flows allocated to specific teams                                                                                  |
| flows.unallocated       | Flows not allocated to any team, shared by teams without an allocation                                             |
| teams[].id              | Team ID                                                                                                            |
| teams[].name            | Team name                                                                                                          |
| teams[].flows_used      | Flows currently used by stories in this team                                                                       |
| teams[].flows_allocated | Flows allocated to this team. `null` when the team has no allocation and draws from the tenant's unallocated flows |
| teams[].flows_available | Allocated flows not yet used by this team. `null` when the team has no allocation                                  |

### Sample response

```json
{
  "flows": {
    "used": 75,
    "limit": 500,
    "allocated": 150,
    "unallocated": 350
  },
  "teams": [
    {
      "id": 1,
      "name": "Security",
      "flows_used": 45,
      "flows_allocated": 100,
      "flows_available": 55
    },
    {
      "id": 2,
      "name": "IT",
      "flows_used": 30,
      "flows_allocated": 50,
      "flows_available": 20
    },
    {
      "id": 3,
      "name": "Engineering",
      "flows_used": 0,
      "flows_allocated": null,
      "flows_available": null
    }
  ],
  "meta": {
    "current_page": "http://<tenant-domain>/api/v1/reporting/flow_usage?per_page=20&page=1",
    "previous_page": null,
    "next_page": null,
    "next_page_number": null,
    "per_page": 20,
    "pages": 1,
    "count": 3
  }
}
```