Nirvana Counts API

The Counts API from Nirvana — 1 operation(s) for counts.

GitHub OpenAPI

Operations 1

GET /v1/counts Task counts per GTD state #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/nirvanahq-com:nirvanahq-com-counts-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

nirvanahq-com-counts-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Nirvana Task Counts API
  version: 1.0.0-beta
  description: 'Nirvana Task API (Public Beta). Clean REST endpoints for integrations, automation, and AI agents (MCP servers, scripts, webhooks). Auth: `Bearer `. Legacy v0 endpoints are removed from this service; migrate integrations to /v1/* endpoints. During beta, backward compatibility is best-effort and minor response changes may occur before GA.'
servers:
- url: https://api.nirvanahq.com
security:
- bearerAuth: []
tags:
- name: Counts
paths:
  /v1/counts:
    get:
      operationId: v1GetCounts
      summary: Task counts per GTD state
      description: 'Returns task counts per GTD state for a quick system overview. "focus" is the starred/Focus list count. With `profile=mcp`, returns `McpCountsResponse` instead: each list''s count with the search query that produces it (searching that query returns exactly that many tasks), due-today sub-counts, and weekly-review checks. It takes the search clock and scope parameters (`now`, `tz`, `weekstart`, `area`, `areamode`).'
      tags:
      - Counts
      parameters:
      - name: profile
        in: query
        description: '`mcp` for counts built from search queries. Omit for the legacy counts.'
        schema:
          type: string
          enum:
          - mcp
      - $ref: '#/components/parameters/Now'
      - $ref: '#/components/parameters/Tz'
      - $ref: '#/components/parameters/Weekstart'
      - $ref: '#/components/parameters/Area'
      - $ref: '#/components/parameters/Areamode'
      responses:
        '200':
          description: Counts per state, or the query-backed counts with profile=mcp
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/McpCountsResponse'
                - type: object
                  required:
                  - ok
                  - counts
                  properties:
                    ok:
                      type: boolean
                    counts:
                      type: object
                      properties:
                        inbox:
                          type: integer
                        next:
                          type: integer
                        waiting:
                          type: integer
                        scheduled:
                          type: integer
                        someday:
                          type: integer
                        later:
                          type: integer
                        focus:
                          type: integer
                        projects:
                          type: integer
                        reflists:
                          type: integer
                        trash:
                          type: integer
              example:
                ok: true
                counts:
                  inbox: 1
                  next: 40
                  waiting: 0
                  scheduled: 0
                  someday: 3
                  later: 0
                  focus: 33
                  projects: 7
                  reflists: 4
                  trash: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/TooManyTasks'
components:
  responses:
    TooManyTasks:
      description: 'Search, counts or vocabulary declined: the account has more rows to search than the server reads at once (20,000 by default). Retrying or narrowing the query does not help; the whole account is loaded before filtering.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
              code:
                type: string
                enum:
                - too_many_tasks
              limit:
                type: integer
              error:
                type: string
          example:
            ok: false
            code: too_many_tasks
            limit: 20000
            error: This account has more than 20,000 tasks to search, more than search can read at once. This usually means repeating tasks or an automation have built up a large backlog. Contact Nirvana support at support@nirvanahq.com and we can help clean it up.
    Unauthorized:
      description: Missing or invalid Bearer token
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
          example:
            error: Unauthorized
    BadRequest:
      description: Invalid request (body or query parameters)
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
              code:
                type: string
                description: Search-grammar reads only (search mode, profile=mcp). `invalid_request` for a bad parameter; `unknown_view`, `invalid_cursor` or `cursor_mismatch` for a bad view or cursor.
              error:
                type: string
          example:
            ok: false
            error: name is required
  parameters:
    Area:
      name: area
      in: query
      description: Grammar reads only (search mode, profile=mcp). Area scope (all, none or an area name). Default all.
      schema:
        type: string
    Areamode:
      name: areamode
      in: query
      description: Grammar reads only (search mode, profile=mcp). Whether rows with no area stay in an area scope. Defaults to the user's stored area-filtering preference (exclusive when unset).
      schema:
        type: string
        enum:
        - inclusive
        - exclusive
    Tz:
      name: tz
      in: query
      description: Grammar reads only (search mode, profile=mcp). IANA zone or UTC offset for "today". Default the user's stored GMT offset.
      schema:
        type: string
    Now:
      name: now
      in: query
      description: Grammar reads only (search mode, profile=mcp). The evaluation instant (ISO 8601 with offset). Default the server clock.
      schema:
        type: string
    Weekstart:
      name: weekstart
      in: query
      description: Grammar reads only (search mode, profile=mcp). First day of the week for week ranges. Defaults to the user's stored week start (sun when unset).
      schema:
        type: string
        enum:
        - sun
        - mon
  schemas:
    McpScope:
      type: object
      properties:
        area:
          type: string
        areamode:
          type:
          - string
          - 'null'
          enum:
          - inclusive
          - exclusive
          - null
    McpCountsResponse:
      type: object
      required:
      - ok
      - grammar_version
      - lists
      description: 'GET /v1/counts?profile=mcp: each count is the total of its `query` (and `due` of its `due_query`), so an agent can list exactly what it counted. Finished work is not a list here; ask is:done.

        '
      properties:
        ok:
          type: boolean
        grammar_version:
          type: integer
        today:
          type: string
          format: date
        timezone:
          type: string
        scope:
          $ref: '#/components/schemas/McpScope'
        lists:
          type: array
          items:
            type: object
            properties:
              list:
                type: string
                enum:
                - inbox
                - focus
                - next
                - later
                - waiting
                - scheduled
                - someday
                - projects
                - reference
                - trash
              count:
                type: integer
              query:
                type: string
              due:
                type: integer
              due_query:
                type: string
              feature_off:
                type: boolean
                description: Present (true) when the account has this list's feature turned off (Settings > Workflow > Features) but the list still holds items. A switched-off list that is empty is not listed at all; Focus switched off is never listed (its tasks are in Next). Later is off unless the account enabled it.
              note:
                type: string
                description: 'With feature_off: what to tell the user (the feature is off; N items remain; help re-file them).'
        review:
          type: array
          items:
            type: object
            properties:
              check:
                type: string
              count:
                type: integer
              query:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer