{
  "openapi": "3.0.1",
  "info": {
    "title": "Hugging Face Model Rankings API & Monitor",
    "description": "See who ranks in a Hugging Face Hub task top-N or on a named model watchlist. Export the public catalog, then monitor downloads, likes, license and rank changes through the official Hub API. No HTML scrape, model weights or login. Schedule the same query to catch rank moves without a full re-export.",
    "version": "0.1",
    "x-build-id": "GJ0BxRCI58gucgb9p"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/automa-flow~huggingface-model-rankings-monitor/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-automa-flow-huggingface-model-rankings-monitor",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/automa-flow~huggingface-model-rankings-monitor/runs": {
      "post": {
        "operationId": "runs-sync-automa-flow-huggingface-model-rankings-monitor",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/automa-flow~huggingface-model-rankings-monitor/run-sync": {
      "post": {
        "operationId": "run-sync-automa-flow-huggingface-model-rankings-monitor",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "queries"
        ],
        "properties": {
          "queries": {
            "title": "Model segments and watchlists",
            "minItems": 1,
            "maxItems": 20,
            "type": "array",
            "description": "One to 20 Hugging Face Hub ranking or watchlist queries. A ranking is a Hub list (task, author and/or search, sorted, top N). A watchlist is explicit model ids. One bad query does not fail the others.",
            "items": {
              "type": "object",
              "properties": {
                "kind": {
                  "title": "Query kind",
                  "type": "string",
                  "description": "segment lists a Hub ranking. watchlist fetches specific public model ids.",
                  "editor": "select",
                  "enum": [
                    "segment",
                    "watchlist"
                  ],
                  "enumTitles": [
                    "Hub ranking (task / author / search)",
                    "Model watchlist"
                  ],
                  "default": "segment"
                },
                "pipelineTag": {
                  "title": "Pipeline tag",
                  "type": "string",
                  "description": "Hub pipeline_tag filter, for example text-generation. Optional. Max 80 characters.",
                  "editor": "textfield",
                  "maxLength": 80
                },
                "author": {
                  "title": "Author",
                  "type": "string",
                  "description": "Hub org or user. Letters, numbers, '.', '_' and '-'. Optional.",
                  "editor": "textfield",
                  "maxLength": 80
                },
                "search": {
                  "title": "Search",
                  "type": "string",
                  "description": "Hub search string. Optional. Max 200 characters.",
                  "editor": "textfield",
                  "maxLength": 200
                },
                "sort": {
                  "title": "Sort",
                  "type": "string",
                  "description": "Hub sort key. Use trendingScore, not trending.",
                  "editor": "select",
                  "enum": [
                    "downloads",
                    "likes",
                    "trendingScore",
                    "lastModified"
                  ],
                  "enumTitles": [
                    "Downloads",
                    "Likes",
                    "Trending score",
                    "Last modified"
                  ],
                  "default": "downloads"
                },
                "topN": {
                  "title": "Top N",
                  "type": "integer",
                  "description": "How many public models to keep for a segment. Ignored for watchlist. Default 20, max 100.",
                  "minimum": 1,
                  "maximum": 100,
                  "default": 20
                },
                "modelIds": {
                  "title": "Hugging Face model ids",
                  "type": "array",
                  "description": "Watchlist only. namespace/name ids or huggingface.co URLs, 1-100. Segment queries ignore this field. Duplicates inside one query are dropped.",
                  "editor": "stringList",
                  "minItems": 1,
                  "maxItems": 100,
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "mode": {
            "title": "Mode",
            "enum": [
              "snapshot",
              "monitor"
            ],
            "type": "string",
            "description": "Get current catalog returns every matching public model and writes no history. Monitor changes compares this successful run with the last successful run of the same query in the same state namespace.",
            "default": "snapshot"
          },
          "outputMode": {
            "title": "Model output",
            "enum": [
              "all",
              "changesOnly"
            ],
            "type": "string",
            "description": "All models returns every current row, including UNCHANGED rows with metric deltas. Changes only omits UNCHANGED rows. Snapshot plus changesOnly is rejected before any Hub request.",
            "default": "all"
          },
          "stateNamespace": {
            "title": "State namespace",
            "minLength": 1,
            "maxLength": 64,
            "type": "string",
            "description": "Isolates monitor history. Use a stable name per watch, for example textgen-top20. Letters, numbers, '_' and '-', 1-64 characters. Snapshot mode ignores it.",
            "default": "default"
          },
          "maxModelRows": {
            "title": "Max model rows",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "Cap on delivered SUCCESS model_observation rows for the whole run. Per-id NOT_FOUND / FAILED rows, query_status and run_summary rows are free and not counted. A query that would exceed the remaining cap is skipped as a whole (PARTIAL/OUTPUT_LIMIT), not truncated.",
            "default": 200
          },
          "metricChangeThresholdPct": {
            "title": "Metric change threshold (%)",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "Monitor mode only. Hub downloads (rolling 30 days), likes and trendingScore drift on almost every model every day, so by default they never classify a row: you get them as downloads_delta / likes_delta on every row and a quiet day stays quiet. Set a percentage (0-1000) to also emit UPDATED when a metric moves by at least that share of its previous value; 0 means any metric change is UPDATED. Rank, presence, license, gated, pipeline_tag, library_name and lastModified always classify."
          },
          "confirmMassRemoval": {
            "title": "Confirm a reviewed ranking reshuffle",
            "type": "boolean",
            "description": "One-off recovery only: accept a complete ranking that retained less than 50% of the previous models. Requires monitor mode and exactly one segment query. Review the Hub ranking first. Keeps history and the two-check EXITED rule. Leave false for scheduled runs; cannot override source failures or incomplete pages.",
            "default": false
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}