Segment Optimization

After a segment is live, you can refine it by expanding its reach or blocking unwanted inventory. Submit an optimization request specifying what to add or exclude, and Classify will update the segment accordingly.

Propagation delay

Segment changes are applied within 2–3 hours, but previously targeted URLs and domains may continue to appear for up to one week while SSP and DSP filters phase out old targeting.

The optimization object

{
  "id": 87,
  "segment_id": 61,
  "status": "accepted",
  "expand": {
    "urls": ["https://www.wsj.com/articles/ev-battery-supply-chain"],
    "domains": ["electrek.co"]
  },
  "block": {
    "urls": ["https://clickbait-site.com/article-123"],
    "domains": ["clickbait-site.com"],
    "keywords": ["gambling", "crypto"]
  },
  "estimated_propagation_hours": 3,
  "created_date": "2026-02-16T14:30:00Z"
}

Field	Type	Description
`id`	integer	Unique identifier for this optimization request
`segment_id`	integer	The segment being optimized
`status`	string	`accepted` on success
`expand`	object \| null	URLs and domains submitted to find similar content
`block`	object \| null	URLs, domains, and keywords to exclude from the segment
`estimated_propagation_hours`	integer	Hours until the change is reflected in the segment. Typically `3`.
`created_date`	string (ISO 8601)	When the optimization request was submitted

Optimize a segment

POST https://api.clsfy.me/v1/clsfy/optimizations

Include at least one of expand or block in your request. You can submit both in a single call.

Parameters

Parameter	Type	Required	Description
`segment_id`	integer	Required	The segment to optimize. Must have `status: "complete"`.
`expand`	object	Optional	New seed content for the segment to find similar URLs.
`expand.urls`	array[string]	Optional	URLs representing the kind of content you want more of.
`expand.domains`	array[string]	Optional	Domains representing the kind of content you want more of.
`block`	object	Optional	Content to exclude from the segment.
`block.urls`	array[string]	Optional	Specific URLs to remove.
`block.domains`	array[string]	Optional	Entire domains to remove.
`block.keywords`	array[string]	Optional	Keywords — any URL whose content matches will be excluded.

Request — Expand

Add new seed URLs and domains to broaden the segment.

curl
Python

curl -X POST "https://api.clsfy.me/v1/clsfy/optimizations" \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_id": 61,
    "expand": {
      "urls": [
        "https://www.wsj.com/articles/ev-battery-supply-chain",
        "https://techcrunch.com/2026/01/10/solid-state-batteries/"
      ],
      "domains": ["electrek.co", "insideevs.com"]
    }
  }'

import requests

response = requests.post(
    "https://api.clsfy.me/v1/clsfy/optimizations",
    headers={
        "X-API-Key": "<your_api_key>",
        "Content-Type": "application/json",
    },
    json={
        "segment_id": 61,
        "expand": {
            "urls": [
                "https://www.wsj.com/articles/ev-battery-supply-chain",
                "https://techcrunch.com/2026/01/10/solid-state-batteries/",
            ],
            "domains": ["electrek.co", "insideevs.com"],
        },
    },
)

optimization = response.json()
print(optimization["status"])  # "accepted"

Request — Block

Remove unwanted inventory from the segment.

curl
Python

curl -X POST "https://api.clsfy.me/v1/clsfy/optimizations" \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_id": 61,
    "block": {
      "urls": ["https://clickbait-site.com/article-123"],
      "domains": ["clickbait-site.com", "spam-news.net"],
      "keywords": ["gambling", "crypto"]
    }
  }'

import requests

response = requests.post(
    "https://api.clsfy.me/v1/clsfy/optimizations",
    headers={
        "X-API-Key": "<your_api_key>",
        "Content-Type": "application/json",
    },
    json={
        "segment_id": 61,
        "block": {
            "urls": ["https://clickbait-site.com/article-123"],
            "domains": ["clickbait-site.com", "spam-news.net"],
            "keywords": ["gambling", "crypto"],
        },
    },
)

optimization = response.json()
print(optimization["status"])  # "accepted"

Request — Expand and block together

You can expand and block in a single request.

curl
Python

curl -X POST "https://api.clsfy.me/v1/clsfy/optimizations" \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_id": 61,
    "expand": {
      "urls": ["https://www.wsj.com/articles/ev-battery-supply-chain"],
      "domains": ["electrek.co"]
    },
    "block": {
      "domains": ["clickbait-site.com"],
      "keywords": ["gambling"]
    }
  }'

import requests

response = requests.post(
    "https://api.clsfy.me/v1/clsfy/optimizations",
    headers={
        "X-API-Key": "<your_api_key>",
        "Content-Type": "application/json",
    },
    json={
        "segment_id": 61,
        "expand": {
            "urls": ["https://www.wsj.com/articles/ev-battery-supply-chain"],
            "domains": ["electrek.co"],
        },
        "block": {
            "domains": ["clickbait-site.com"],
            "keywords": ["gambling"],
        },
    },
)

optimization = response.json()
print(optimization["id"])  # e.g. 87
print(f"Changes will propagate in ~{optimization['estimated_propagation_hours']} hours")

Response

Returns the optimization object immediately with status: "accepted".

{
  "id": 87,
  "segment_id": 61,
  "status": "accepted",
  "expand": {
    "urls": ["https://www.wsj.com/articles/ev-battery-supply-chain"],
    "domains": ["electrek.co"]
  },
  "block": {
    "domains": ["clickbait-site.com"],
    "keywords": ["gambling"]
  },
  "estimated_propagation_hours": 3,
  "created_date": "2026-02-16T14:30:00Z"
}

No polling needed

Unlike segment creation and activation, optimization requests do not require polling. The response confirms the request was accepted. The segment will be updated within the estimated_propagation_hours window.

Get an optimization

Retrieve a previous optimization request by ID.

GET https://api.clsfy.me/v1/clsfy/optimizations/{id}

Parameter	Type	Description
`id`	integer	The optimization ID returned at creation

curl
Python

curl "https://api.clsfy.me/v1/clsfy/optimizations/87" \
  -H "X-API-Key: <your_api_key>"

import requests

response = requests.get(
    "https://api.clsfy.me/v1/clsfy/optimizations/87",
    headers={"X-API-Key": "<your_api_key>"},
)

optimization = response.json()
print(optimization)

Error responses

When a request fails, the API returns a JSON object with an error code and a human-readable message:

{
  "error": "not_found",
  "message": "Segment with ID 999 not found"
}

HTTP status codes

Status	Meaning
`200 OK`	Success
`201 Created`	Resource created (POST endpoints)
`400 Bad Request`	Invalid or missing parameters
`401 Unauthorized`	Missing or invalid API key
`404 Not Found`	Resource not found
`422 Unprocessable Content`	Validation error (e.g. invalid field values)
`429 Too Many Requests`	Rate limit exceeded

The optimization object​

Optimize a segment​

Parameters​

Request — Expand​

Request — Block​

Request — Expand and block together​

Response​

Get an optimization​

Error responses​

HTTP status codes​