# Topic (`topic-1`): Topic and format classification

What a page is about and what kind of page it is.

Topic labels a web page or article with one of 24 topics (health, finance and business, software development, travel...) and one of 24 formats (tutorial, news article, product page, forum thread...).

It's built for crawling and content pipelines: filter a scrape down to tutorials about software, or keep product pages out of a news index.

- **Price:** $0.02 per 1,000 texts. One unit per text up to 2,000 characters; longer texts are split into 2,000-character chunks and each chunk is a unit.
- **Languages:** 65 languages
- **Input:** Page text (not a URL), a string or an array of up to 64. The first ~2,000 characters decide the labels.
- **Batch:** yes, up to 64 inputs per call
- **Status:** live
- **Built on:** [Horizon-Labs/multilingual-web-topic-format-small](https://huggingface.co/Horizon-Labs/multilingual-web-topic-format-small), Apache-2.0, 141M (mmBERT-small encoder)

## Request

```bash
curl https://labs.greatwork.company/v1/run \
  -H "Authorization: Bearer $GWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"topic-1","input":"Step 1: Install the CLI with brew install. Step 2: Run init in your project folder to create a config file. Step 3: Add your API key to the config and run the first deploy."}'
```

## Options

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `input` | string or string[] | yes | | Page text (not a URL), a string or an array of up to 64. The first ~2,000 characters decide the labels. |


## Output

| Field | Type | Description |
|---|---|---|
| `topic` | object | Best topic: `label`, `score`. |
| `format` | object | Best format: `label`, `score`. |
| `topics` | object[] | Top 5 topics with scores. |
| `formats` | object[] | Top 5 formats with scores. |

The response envelope is always `{"id", "object": "run", "model", "created", "output", "usage": {"units", "unit", "cost_usd", "cost_micros"}, "latency_ms"}`. With an array input, `output` is an array in the same order.

## Examples (real outputs from our servers)

### Tutorial

```json
{
  "model": "topic-1",
  "input": "Step 1: Install the CLI with brew install. Step 2: Run init in your project folder to create a config file. Step 3: Add your API key to the config and run the first deploy."
}
```

```json
{
  "topic": {
    "label": "software_development",
    "score": 0.874
  },
  "format": {
    "label": "tutorial_how_to_guide",
    "score": 0.7901
  },
  "topics": [
    {
      "label": "software_development",
      "score": 0.874
    },
    {
      "label": "software",
      "score": 0.1563
    },
    {
      "label": "industrial",
      "score": 0.0006
    },
    {
      "label": "science_math_technology",
      "score": 0.0006
    },
    {
      "label": "games",
      "score": 0.0003
    }
  ],
  "formats": [
    {
      "label": "tutorial_how_to_guide",
      "score": 0.7901
    },
    {
      "label": "technical_writing",
      "score": 0.0934
    },
    {
      "label": "spam_ads",
      "score": 0.0483
    },
    {
      "label": "structured_data",
      "score": 0.0105
    },
    {
      "label": "customer_support_page",
      "score": 0.0037
    }
  ]
}
```

64 ms, $0.00002.

### Recipe

```json
{
  "model": "topic-1",
  "input": "Preheat the oven to 200C. Toss the potatoes with olive oil, garlic and rosemary, spread them on a tray and roast for 40 minutes, turning once."
}
```

```json
{
  "topic": {
    "label": "food_dining",
    "score": 0.9999
  },
  "format": {
    "label": "tutorial_how_to_guide",
    "score": 0.9941
  },
  "topics": [
    {
      "label": "food_dining",
      "score": 0.9999
    },
    {
      "label": "religion",
      "score": 0.001
    },
    {
      "label": "entertainment",
      "score": 0.0003
    },
    {
      "label": "education_jobs",
      "score": 0.0001
    },
    {
      "label": "art_design",
      "score": 0.0001
    }
  ],
  "formats": [
    {
      "label": "tutorial_how_to_guide",
      "score": 0.9941
    },
    {
      "label": "incomplete_content",
      "score": 0.0014
    },
    {
      "label": "spam_ads",
      "score": 0.0011
    },
    {
      "label": "news_article",
      "score": 0.001
    },
    {
      "label": "customer_support_page",
      "score": 0.0004
    }
  ]
}
```

48 ms, $0.00002.

### Product page

```json
{
  "model": "topic-1",
  "input": "Merino Wool Crew Sock, 3-pack. $24.00. Free returns. Made in Portugal from 80% merino wool. Sizes S to XL. Add to cart."
}
```

```json
{
  "topic": {
    "label": "fashion_beauty",
    "score": 0.9469
  },
  "format": {
    "label": "product_page",
    "score": 0.9845
  },
  "topics": [
    {
      "label": "fashion_beauty",
      "score": 0.9469
    },
    {
      "label": "home_hobbies",
      "score": 0.019
    },
    {
      "label": "sports_fitness",
      "score": 0.0122
    },
    {
      "label": "industrial",
      "score": 0.0065
    },
    {
      "label": "adult_content",
      "score": 0.0051
    }
  ],
  "formats": [
    {
      "label": "product_page",
      "score": 0.9845
    },
    {
      "label": "spam_ads",
      "score": 0.0095
    },
    {
      "label": "structured_data",
      "score": 0.0009
    },
    {
      "label": "legal_notices",
      "score": 0.0007
    },
    {
      "label": "faqs",
      "score": 0.0003
    }
  ]
}
```

57 ms, $0.00002.

## Good for

- Filter crawled pages before indexing
- Build training data mixes by topic
- Group a site's pages for an SEO audit
- Keep product pages out of a news feed

## Limits and caveats

- One topic and one format per page; many pages fit several.
- Rare categories are weaker.
