> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corpus.intrace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Actor Types Reference

> Complete list of actor type values in the Intrace Corpus

# Actor Types

The Intrace Corpus classifies actors into distinct types to enable precise filtering and analysis. Actor types are used as query parameters to filter results when listing actors.

## Overview

Actor types are used to categorize entities involved in events. The classification system covers:

* **Government and state actors**
* **Military and security forces**
* **Political organizations and parties**
* **Non-state armed groups**
* **Criminal organizations**
* **Civil society and activist groups**
* **Media and press**
* **International organizations**
* **Corporations and businesses**
* **Individuals**

## Using Actor Types in Queries

### List Actors by Type

```python theme={null}
import requests

# Get all government actors
response = requests.get(
    "https://api.corpus.intrace.ai/v1/actors",
    headers={"X-API-Key": "your-api-key"},
    params={"actor_type": "state_government"}
)
```

### Discover Available Actor Types

Use the metadata endpoint to see all actor types currently in the corpus:

```python theme={null}
# Get all actor types with counts
response = requests.get(
    "https://api.corpus.intrace.ai/v1/metadata/actor-types",
    headers={"X-API-Key": "your-api-key"}
)
actor_types = response.json()
```

## Actor Type Definitions

The following actor types are commonly found in the corpus. Use the metadata endpoint above to get the current complete list with counts.

### State & Government

* **National Government**: Federal/central government bodies
* **Regional Government**: State, provincial, or regional authorities
* **Local Government**: Municipal or local government entities
* **Government Agency**: Specific government departments or agencies
* **Law Enforcement**: Police, national guard, and law enforcement bodies
* **Military**: Armed forces and military organizations
* **Intelligence Agency**: Intelligence and security services

### Political Organizations

* **Political Party**: Registered political parties and movements
* **Political Coalition**: Alliances of political parties
* **Opposition Group**: Opposition political movements

### Armed Groups

* **Rebel Group**: Armed opposition forces
* **Militia**: Non-state armed militias
* **Paramilitary**: Paramilitary organizations
* **Terrorist Organization**: Designated terrorist groups

### Criminal Organizations

* **Cartel**: Drug cartels and trafficking organizations
* **Gang**: Street gangs and organized crime groups
* **Mafia**: Traditional organized crime syndicates

### Civil Society

* **NGO**: Non-governmental organizations
* **Activist Group**: Civil society and activist movements
* **Labor Union**: Trade unions and labor organizations
* **Religious Group**: Religious organizations and movements

### Media & Press

* **Media Outlet**: News organizations and media companies
* **Journalist**: Individual journalists and correspondents

### International

* **International Organization**: UN, regional bodies (AU, EU, etc.)
* **Foreign Government**: Governments of other nations
* **Multinational Alliance**: NATO, coalitions, etc.

### Corporate

* **Corporation**: Private companies and businesses
* **Industry Group**: Industry associations and lobbying groups

### Individual

* **Individual**: Named individuals (politicians, activists, etc.)
* **Unknown**: Unidentified or unattributed actors

## Actor Hierarchy

Events, particularly conflict events, often involve multiple actors in different hierarchical positions. The Corpus API distinguishes between internal organizational units and external supporting actors:

### Position Types

* **Principal**: Primary actor in the event (mapped to `actor1` in ACLED format)
* **Secondary**: Secondary or opposing actor (mapped to `actor2` in ACLED format)
* **Sub-Principal/Sub-Secondary**: Internal sub-units, factions, or branches within the same organization
* **Supporting Principal/Supporting Secondary**: External actors from different organizations providing support

### Key Distinction: Internal vs External

**Internal Sub-Actors (sub\_principal/sub\_secondary):**

* Part of the same organization as the main actor
* Examples: military divisions, battalions, regional branches, factions within a group
* Use case: "Nigerian Army" (principal) with "7th Division" and "3rd Battalion" as sub-principal actors

**External Supporting Actors (supporting\_principal/supporting\_secondary):**

* Separate organizations providing support to the main actor
* Examples: foreign military support, allied groups, coalition partners
* Use case: "Colombian Army" (principal) with "U.S. Special Forces" as supporting\_principal providing training

### Examples

**Example 1: Military operation with foreign support**

```
Principal: Nigerian Army
Sub-Principal: 7th Division, 3rd Battalion
Supporting Principal: French Air Force, U.S. Military Advisors

Secondary: Boko Haram
Sub-Secondary: Shekau Faction
Supporting Secondary: null
```

**Example 2: Rebel coalition**

```
Principal: Free Syrian Army
Sub-Principal: Southern Front, Damascus Brigade
Supporting Principal: Turkish Armed Forces

Secondary: Syrian Arab Army
Sub-Secondary: 4th Armored Division, Republican Guard
Supporting Secondary: Russian Aerospace Forces, Hezbollah
```

**Example 3: Inter-cartel violence**

```
Principal: Sinaloa Cartel
Sub-Principal: Los Chapitos Faction
Supporting Principal: null

Secondary: Jalisco New Generation Cartel
Sub-Secondary: Elite Group
Supporting Secondary: null
```

See the [Event Data Models](/guides/corpus-api/taxonomy/data-models) page for complete field specifications and export format details.

## Actor Attributes

### Institution Stance

The `institution_stance` field describes the actor's orientation toward established governmental and state institutions. It is set by AI during actor canonicalization and may be overridden manually.

| Value              | Description                                                    |
| ------------------ | -------------------------------------------------------------- |
| `pro_institution`  | Supports existing state authority and institutional structures |
| `anti_institution` | Actively opposes state authority and institutional structures  |
| `neutral`          | No clear alignment toward or against state institutions        |
| `unknown`          | Insufficient information to determine institutional stance     |

## Filtering Events by Actor Type

The events endpoint does not filter directly by actor type, but you can combine the actors and actor events endpoints to achieve this efficiently:

1. **Find actors of a specific type** (supports multi-value and numeric range filters)
2. **Get events for those actors** (supports full event filter and sort surface)

```python theme={null}
# Step 1: Find all rebel group actors in a country with event activity
actors_response = requests.get(
    "https://api.corpus.intrace.ai/v1/actors",
    headers={"X-API-Key": "your-api-key"},
    params=[
        ("actor_type", "rebel_group"),
        ("actor_type", "militia"),
        ("country", "SY"),
        ("event_count_min", "5"),
    ]
)
actors = actors_response.json()["items"]

# Step 2: Get filtered, sorted events for a specific actor
for actor in actors:
    events_response = requests.get(
        f"https://api.corpus.intrace.ai/v1/actors/{actor['id']}/events",
        headers={"X-API-Key": "your-api-key"},
        params={
            "event_category": "conflict",
            "date_from": "2025-01-01",
            "salience_score_min": "0.5",
            "sort_by": "salience_score",
            "sort_order": "desc",
        }
    )
    events = events_response.json()
```

The `/actors/{id}/events` endpoint accepts the same filter and sort parameters as `/events`, so you can narrow results without client-side filtering.

[← Back to Taxonomy Overview](/guides/corpus-api/taxonomy)