> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server.

# Find organization axes

> Discover the best dimensions for organizing your videos and images, scored by effectiveness.

This recipe shows you how to discover the best dimensions for organizing your videos and images. The response includes ranked categorization strategies with effectiveness scores, expected groups, and example categories, ready for data-driven organization decisions.

**Use cases**:

* **New collection exploration**: Discover natural groupings in videos and images you haven't categorized yet
* **Strategy comparison**: Evaluate categorization approaches side by side before committing to a taxonomy
* **Organization pipeline**: Feed scored axes into a workflow that categorizes every item

# Key concepts

* **Knowledge store**: A persistent store of your videos and images plus the understanding the platform derives from them - spatiotemporal context, a typed ontology, and embeddings - that together enable corpus-level reasoning.
* **Instructions**: Additional guidance that shapes Jockey's behavior for a specific domain or task.
* **Structured output**: A JSON schema you provide with your request. Jockey constrains its output to match your schema, so you retrieve machine-readable results instead of plain text. For a guide on designing schemas and parsing responses, see the [Structured output](/v1.3/agents/guides/create-a-response/structured-output) page.

# Workflow

This recipe combines three elements: a JSON schema that defines the axis data structure, instructions that give [Jockey](/v1.3/agents/concepts/jockey) a specific role and domain guidance, and a prompt that describes what you want evaluated. Jockey reasons across your knowledge store, evaluates possible categorization strategies, and returns ranked results with effectiveness scores. You can adapt this recipe to evaluate different domains or apply different ranking criteria.

# Prerequisites

* You've already created a knowledge store with at least one item in `ready` status. See the [Create a knowledge store](/v1.3/agents/guides/create-a-knowledge-store) and [Add assets to a knowledge store](/v1.3/agents/guides/add-assets) guides for details.
* You're familiar with the request and response format. See the [Create a response](/v1.3/agents/guides/create-a-response) page for details.

# Complete example

Copy and paste the code below, replacing the placeholders surrounded by `<>` with your values.

**`Python`**

```python Python maxlines=40
import json
from twelvelabs import TwelveLabs, TextParam
from twelvelabs.types.text_param_format import TextParamFormat_JsonSchema

client = TwelveLabs(api_key="<YOUR_API_KEY>")
STORE_ID = "<YOUR_KNOWLEDGE_STORE_ID>"

# Define a JSON schema for the organization axes
axes_schema = {
    "type": "object",
    "properties": {
        "axes": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "axis": {"type": "string"},                # Name of the categorization dimension
                    "description": {"type": "string"},         # What this axis measures or captures
                    "expected_groups": {"type": "integer"},     # Estimated number of categories
                    "example_categories": {                     # Sample category names
                        "type": "array",
                        "items": {"type": "string"},
                    },
                    "effectiveness_score": {"type": "number"}, # 0-1 score for separation quality
                    "rationale": {"type": "string"},           # Why this axis works well (or not)
                },
            },
        },
        "recommendation": {"type": "string"},                  # Overall best-strategy recommendation
    },
}

# Rank the organization strategies
response = client.responses.create(
    knowledge_store_id=STORE_ID,
    instructions="You are a content strategist. Analyze these videos and images and recommend the most effective ways to organize them. Score each axis by how well it separates content into distinct, useful groups.",
    input=[{"type": "message", "role": "user", "content": "What are the top 5 best ways to organize these videos and images? Score each from 0-1 based on how cleanly it separates the content."}],
    text=TextParam(format=TextParamFormat_JsonSchema(name="organization_axes", schema_=axes_schema)),
)

# Parse and read the strategies
for output in response.output:
    if output.type == "message":
        for content in output.content:
            data = json.loads(content.text)
            print(f"Recommendation: {data['recommendation']}\n")
            for ax in data["axes"]:
                print(f"  {ax['axis']} (score: {ax['effectiveness_score']})")
                print(f"    {ax['description']}")
                print(f"    Groups: {ax['expected_groups']} - {', '.join(ax['example_categories'])}")
                print(f"    Why: {ax['rationale']}\n")
```

**`Node.js`**

```javascript Node.js maxlines=40
import { TwelveLabs } from "twelvelabs-js";

const client = new TwelveLabs({ apiKey: "<YOUR_API_KEY>" });
const storeId = "<YOUR_KNOWLEDGE_STORE_ID>";

// Define a JSON schema for the organization axes
const axesSchema = {
  type: "object",
  properties: {
    axes: {
      type: "array",
      items: {
        type: "object",
        properties: {
          axis: { type: "string" }, // Name of the categorization dimension
          description: { type: "string" }, // What this axis measures or captures
          expected_groups: { type: "integer" }, // Estimated number of categories
          example_categories: { // Sample category names
            type: "array",
            items: { type: "string" },
          },
          effectiveness_score: { type: "number" }, // 0-1 score for separation quality
          rationale: { type: "string" }, // Why this axis works well (or not)
        },
      },
    },
    recommendation: { type: "string" }, // Overall best-strategy recommendation
  },
};

// Rank the organization strategies
const response = await client.responses.create({
  knowledgeStoreId: storeId,
  instructions: "You are a content strategist. Analyze these videos and images and recommend the most effective ways to organize them. Score each axis by how well it separates content into distinct, useful groups.",
  input: [{ type: "message", role: "user", content: "What are the top 5 best ways to organize these videos and images? Score each from 0-1 based on how cleanly it separates the content." }],
  text: { format: { type: "json_schema", name: "organization_axes", schema: axesSchema } },
});

// Parse and read the strategies
for (const output of response.output ?? []) {
  if (output.type === "message") {
    for (const content of output.content ?? []) {
      const data = JSON.parse(content.text);
      console.log(`Recommendation: ${data.recommendation}\n`);
      for (const ax of data.axes) {
        console.log(`  ${ax.axis} (score: ${ax.effectiveness_score})`);
        console.log(`    ${ax.description}`);
        console.log(`    Groups: ${ax.expected_groups} - ${ax.example_categories.join(", ")}`);
        console.log(`    Why: ${ax.rationale}\n`);
      }
    }
  }
}
```

# Code explanation

#### Python

To rank organization strategies, call the [`responses.create`](/v1.3/sdk-reference/python/responses#create-a-response) method with `instructions`, a prompt, and a `text` parameter that describes your result schema.\

**Parameters**:

* `knowledge_store_id`: The unique identifier of the knowledge store to reason over.
* `input`: An array of input items. Each item is a message you send to Jockey. This example asks Jockey to recommend the top five categorization strategies and score each on a 0–1 scale.
* `instructions`: A per-request system prompt that shapes Jockey's behavior for a domain or task. This example uses a content strategist role that evaluates categorization strategies.
* `text`: An object that specifies the response format. To return structured JSON, set the `format` field. Within it, the `schema_` field defines the structure the output must match, and the `name` field identifies the schema. Design the schema to fit your use case; the inline comments in the example describe each field. For the schema rules, see the [Structured output](/v1.3/agents/guides/create-a-response/structured-output#json-schema-requirements) page.\


**Return value**: An object of type `ResponseObject` containing, among other information, the following fields:

* `id`: The unique identifier of the response.
* `knowledge_store_id`: The knowledge store this response was generated against.
* `session_id`: The session identifier. Pass it in a follow-up request to continue the conversation.
* `status`: The status of the response. The possible values are `completed`, `failed`, `in_progress`, and `incomplete`.
* `output`: The response output items. The `text` field of each content part in a `message` item is a JSON string that matches your schema. Parse it with the `json.loads()` method, then iterate the `axes` array to read each ranked strategy.
* `usage`: Token usage statistics, including the `input_tokens` and `output_tokens` fields.

#### Node.js

To rank organization strategies, call the [`responses.create`](/v1.3/sdk-reference/node-js/responses#create-a-response) method with `instructions`, a prompt, and a `text` parameter that describes your result schema. You pass all parameters as properties of a single object.\

**Parameters**:

* `knowledgeStoreId`: The unique identifier of the knowledge store to reason over.
* `input`: An array of input items. Each item is a message you send to Jockey. This example asks Jockey to recommend the top five categorization strategies and score each on a 0–1 scale.
* `instructions`: A per-request system prompt that shapes Jockey's behavior for a domain or task. This example uses a content strategist role that evaluates categorization strategies.
* `text`: An object that specifies the response format. To return structured JSON, set the `format` field. Within it, the `type` field must be `"json_schema"`, the `schema` field defines the structure the output must match, and the `name` field identifies the schema. Design the schema to fit your use case; the inline comments in the example describe each field. For the schema rules, see the [Structured output](/v1.3/agents/guides/create-a-response/structured-output#json-schema-requirements) page.\


**Return value**: An `HttpResponsePromise` that resolves to an object of type `ResponseObject` containing, among other information, the following fields:

* `id`: The unique identifier of the response.
* `knowledgeStoreId`: The knowledge store this response was generated against.
* `sessionId`: The session identifier. Pass it in a follow-up request to continue the conversation.
* `status`: The status of the response. The possible values are `completed`, `failed`, `in_progress`, and `incomplete`.
* `output`: The response output items. The `text` field of each content part in a `message` item is a JSON string that matches your schema. Parse it with the `JSON.parse()` method, then iterate the `axes` array to read each ranked strategy.
* `usage`: Token usage statistics, including the `inputTokens` and `outputTokens` fields.

# Example response

The `text` field inside each content part is a JSON string that matches your schema. After parsing, a typical result looks like this:

```json
{
  "axes": [
    {
      "axis": "Content Type",
      "description": "Groups videos by their format and production style",
      "expected_groups": 4,
      "example_categories": ["tutorials", "product demos", "interviews", "presentations"],
      "effectiveness_score": 0.92,
      "rationale": "Each video clearly fits one format, producing well-separated groups with minimal overlap"
    },
    {
      "axis": "Product Area",
      "description": "Groups videos by the feature or product they cover",
      "expected_groups": 5,
      "example_categories": ["analytics dashboard", "API platform", "mobile SDK", "integrations", "billing"],
      "effectiveness_score": 0.85,
      "rationale": "Videos focus on specific product areas, creating meaningful clusters for feature-based navigation"
    },
    {
      "axis": "Target Audience",
      "description": "Groups videos by the intended viewer",
      "expected_groups": 3,
      "example_categories": ["developers", "product managers", "executives"],
      "effectiveness_score": 0.78,
      "rationale": "Most videos target a clear audience, though some span multiple groups"
    },
    {
      "axis": "Difficulty Level",
      "description": "Groups videos by the assumed prior knowledge of the viewer",
      "expected_groups": 3,
      "example_categories": ["beginner", "intermediate", "advanced"],
      "effectiveness_score": 0.71,
      "rationale": "Difficulty is readable across most content but some videos mix levels within a single session"
    },
    {
      "axis": "Recency",
      "description": "Groups videos by when they were produced relative to product releases",
      "expected_groups": 4,
      "example_categories": ["pre-launch", "launch week", "post-launch", "evergreen"],
      "effectiveness_score": 0.63,
      "rationale": "Useful for filtering out outdated content but requires timestamp metadata to apply reliably"
    }
  ],
  "recommendation": "Content Type produces the cleanest separation. Combine with Product Area as a secondary axis for a two-level taxonomy."
}
```

> **Note**
>
> Jockey evaluates each axis against the actual content in your knowledge store. Scores and recommendations change depending on the videos you have indexed.

# Variations

Change the instructions and prompt to adapt this recipe for different organizational needs.

* **Domain-constrained**: Set the `instructions` parameter to a team-specific perspective: "marketing strategist," "education specialist," or "compliance officer."
* **Audience-centric**: Change the prompt to "How would different audiences want these videos and images organized?"
* **Hierarchical taxonomy**: Change the prompt to "Suggest a two-level taxonomy: primary axes and sub-axes for each."

# Jupyter notebook

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/twelvelabs-io/twelvelabs-developer-experience/blob/main/quickstarts/jockey/recipes/find_organization_axes.ipynb)

# See also

* [Organize a video library](/v1.3/agents/recipes/organize-a-video-library) - uses organization axes as step 2 of a full workflow
* [Structured output](/v1.3/agents/guides/create-a-response/structured-output) - more on JSON Schema responses
* [Create a response](/v1.3/api-reference/responses/create) - API reference for the Responses endpoint