Edit

Migrate from the HTTP Data Collector API to the Logs ingestion API

The HTTP Data Collector API is on a deprecation path. Support for the legacy Data Collector API ends September 14, 2026. Existing ingestion continues to work, but the API only receives critical security fixes. Migrate to the Logs ingestion API which provides more processing power and flexibility in ingesting logs and managing tables.

This article describes the differences between the two APIs and how to migrate to the Logs ingestion API.

Two dates affect Data Collector API ingestion. On March 1, 2026, the API endpoint stopped accepting legacy TLS versions; clients that don't negotiate TLS 1.2 or later can't ingest data. On September 14, 2026, the API is deprecated but ingestion continues for TLS compliant clients. Verify your client's TLS configuration before assuming ingestion is healthy, regardless of your migration timeline.

Advantages of the Logs ingestion API

The Logs ingestion API provides the following advantages over the Data Collector API:

  • Supports transformations, which enable you to modify the data before you ingest it into the destination table, including filtering and data manipulation.
  • Lets you send data to multiple destinations.
  • Lets you manage the destination table schema, including column names, and whether to add new columns to the destination table when the source data schema changes.
  • Supports role-based access control (RBAC) to restrict data ingestion by data collection rule and identity.

Prerequisites

To complete this migration, you need:

Permissions required

The Logs ingestion API uses OAuth-based authentication via Microsoft Entra (for app registrations or managed identities) and data collection rule (DCR) scoped RBAC. Assign the app permissions to the DCR and use a data collection endpoint (DCE) or the DCR logs ingestion endpoint for ingestion requests.

Action Permissions required
Create a data collection endpoint. Microsoft.Insights/dataCollectionEndpoints/write permissions, for example through the Monitoring Contributor built-in role.
Create or modify a data collection rule. Microsoft.Insights/DataCollectionRules/Write permissions, for example through the Monitoring Contributor built-in role.
Convert a table that uses the Data Collector API to data collection rules and the Logs ingestion API. Microsoft.OperationalInsights/workspaces/tables/migrate/action permissions, for example through the Log Analytics Contributor built-in role.
Create new tables or modify table schemas. microsoft.operationalinsights/workspaces/tables/write permissions, for example through the Log Analytics Contributor built-in role.
Call the Logs ingestion API. See Assign permissions to a DCR.

Create new resources required for the Logs ingestion API

The Logs ingestion API requires you to create two new types of resources, which the HTTP Data Collector API doesn't require:

Migrate existing custom tables or create new tables

If you have an existing custom table to which you currently send data by using the Data Collector API, your options are:

  • Migrate the table and switch to the Logs ingestion API.
  • Maintain the existing table and data and set up a new table into which you ingest data by using the Logs ingestion API. Delete the old table when you're ready.
  • (Not recommended) Migrate the table but still use the legacy Data Collector API. Changes to existing data types and multiple schema changes to existing Data Collector API custom tables might lead to errors.

Identify classic custom tables

You have a few ways to find tables that use the Data Collector API:

  • Table properties (portal): View table properties. Tables that use the Data Collector API or ingest data through the legacy Log Analytics agent (MMA) display Custom table (classic) as the Type property.

  • Table properties (API): tableSubType is Classic when viewing table properties with the Table operation of the Logs management API. Here's an example Azure CLI command that quickly finds all tables with this criteria:

az monitor log-analytics workspace table list \
  --resource-group myResourceGroupName --workspace-name myWorkspaceName \
  --query "[?schema.tableSubType=='Classic'].{Name:name, SubType:schema.tableSubType}" -o table
  • Query heuristics: Clues from individual records can help further investigate legacy API usage. Records with the SourceSystem value of RestAPI indicate the record was created by the HTTP Data Collector API, so the table was legacy when the record was created. Also, certain column name suffixes indicate the column was created by the legacy API.

To list tables in a workspace that contain rows ingested through the Data Collector API, run this query:

Suffix conventions for columns created by the legacy API:

Suffix Data type
_s string
_d double
_t datetime

Warning

Migrate from the Log Analytics agent to the Azure Monitor Agent before converting MMA tables. Otherwise, data stops ingesting into custom fields in these tables after the table conversion.

Migration considerations

Microsoft Sentinel connectors are transitioning to Codeless Connector Framework (CCF) connectors available via Content Hub. These CCF connectors use DCRs with the Logs ingestion API. This approach provides DCR-governed schema control, applies transformations for normalization, and improves reliability and scalability compared to the legacy Data Collector API. Migration might introduce new or updated table names and schemas. Old Azure Functions–based connectors that use the legacy HTTP Data Collector API and new CCF connectors might temporarily coexist during the transition period.

When migrating Sentinel connectors, you must update dependent artifacts (analytics rules, hunting queries, workbooks, playbooks, parsers) to reference any new CCF-backed tables or changed schemas. Verify and update KQL queries, alerts, and content packs to prevent ingestion or detection gaps post-migration.

This table summarizes considerations for each option:

Table migration Side-by-side implementation
Table and column naming Reuse existing table name.
Column naming options:
- Use new column names and define a transformation to direct incoming data to the newly named column.
- Continue using old names.		 Set the new table name freely.
Adjust integrations, dashboards, and alerts before switching to the new table.
Migration procedure One-off table migration. Not possible to roll back a migrated table. You can migrate gradually, per table.
Post-migration If you continue to ingest data by using the HTTP Data Collector API with existing columns, don't change the schema.
Create new columns only if you ingest data by using the Logs ingestion API.		 Data in the old table is available until the end of the retention period.
When you first set up a new table or make schema changes, data changes can take 10-15 minutes to appear in the destination table.

Warning

If you're still ingesting through the legacy Data Collector API after you migrate a table, don't use the Tables API or the Edit schema option in the Tables UI to introduce schema changes (for example, adding a new column). Doing so breaks legacy ingestion. If you must continue ingesting by using the Data Collector API, don't make schema changes until you fully migrate to the Logs ingestion API.

Convert a table from V1 to V2

To convert a table that uses the Data Collector API (V1) to data collection rules and the Logs ingestion API (V2), run the migrate operation against the table. If the table is already converted, this operation has no effect.

The following Azure CLI example uses the az monitor log-analytics workspace table migrate command.

# Set variables
resourceGroupName="<ResourceGroupName>"
workspaceName="<WorkspaceName>"
tableName="<TableName_CL>"

# Migrate the table from V1 to V2
az monitor log-analytics workspace table migrate \
  --resource-group "$resourceGroupName" \
  --workspace-name "$workspaceName" \
  --table-name "$tableName"

Note

Azure CLI commands use the Azure Resource Manager endpoint from the current CLI context, so management.azure.com doesn't need to be specified in the command syntax.

The migrate operation enables all DCR-based custom logs features on the table. If the Data Collector API continues to ingest data into existing columns, it doesn't create any new columns. Any previously defined custom fields stop getting new data. Don't change the schema to create new columns or the Data Collector API stops ingesting for the entire table. Apply a workspace transformation to migrate a table to DCRs to delay switching to the Logs ingestion API.

Important

  • Column names must start with a letter and can consist of up to 45 alphanumeric characters and underscores (_).
  • _ResourceId, id, _SubscriptionId, TenantId, Type, UniqueId, and Title are reserved column names.
  • Custom columns you add to an Azure table must have the suffix _CF.
  • If you update the table schema in your Log Analytics workspace, you must also update the input stream definition in the data collection rule to ingest data into new or modified columns.

Reduce data size per call

The Logs ingestion API lets you send up to 1 MB of compressed or uncompressed data per call. If you need to send more than 1 MB of data, you can send multiple calls in parallel. This limit differs from the Data Collector API, which lets you send up to 32 MB of data per call.

To call the Logs ingestion API, see Logs ingestion REST API call.

Handle GUID data type differences

GUIDs are stored as strings in Azure Monitor Logs. The Tables API accepts guid as a column type, but that data type is viewed and written as string type by the Logs query and Logs ingestion APIs respectively. Declare data source GUIDs as string in your DCR streamDeclarations. This behavior is the same for both ingestion APIs, so migrating from the Data Collector API doesn't change how existing GUID values are stored or queried. For more information, see Table column data types.

Handle source data schema changes

The Data Collector API automatically adjusts a destination legacy table's schema when the source data object schema changes, but the Logs ingestion API doesn't. The Logs ingestion API ensures you don't collect new data into columns that you don't intend to create.

Options when the source data schema changes:

Note

You can't reuse a column name with a data type that differs from the column's original data type.

Related content

Microsoft MVP Morten Waltorp Knudsen contributed to this article. For an example of automating the setup and ongoing use of the Logs ingestion API, see his AzLogDcrIngestPS PowerShell module.

  • Last updated on