Skip to main content

​
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

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: 
# 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 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.
ValueDescription
pro_institutionSupports existing state authority and institutional structures
anti_institutionActively opposes state authority and institutional structures
neutralNo clear alignment toward or against state institutions
unknownInsufficient 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)
# 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