Query Tasks

curl --request POST \
  --url https://api.tela.com/task/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "promptApplicationId": "95cec438-6080-44fe-8275-28b16bd40178",
  "filters": {
    "status": [
      "completed"
    ],
    "createdAtSince": "2025-01-01T00:00:00Z",
    "tags": [
      "priority"
    ]
  },
  "outputQuery": {
    "cliente": "Acme Corporation",
    "valor": {
      "$gte": 100000,
      "$lte": 500000
    },
    "lineItems": {
      "$elemMatch": {
        "amount": {
          "$gt": 1000
        }
      }
    }
  },
  "select": [
    "cliente",
    "valor"
  ],
  "orderBy": "createdAt",
  "order": "desc",
  "limit": 20,
  "offset": 0
}
'

{
  "data": [
    {
      "taskId": "8b6d2c9a-1f4e-4c1b-9a1e-3c2d5e6f7a80",
      "taskName": "Invoice-2025-001.pdf",
      "status": "completed",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "approvedAt": "2025-01-15T11:00:00.000Z",
      "input": {
        "variables": {
          "document": {
            "files": [
              {
                "file_url": "https://example.com/invoice.pdf",
                "file_name": "Invoice-2025-001.pdf",
                "mime_type": "application/pdf"
              }
            ]
          }
        },
        "messages": [],
        "files": [
          {
            "name": "document",
            "filename": "Invoice-2025-001.pdf",
            "url": "https://example.com/invoice.pdf",
            "usedAt": "variables",
            "mimeType": "application/pdf"
          }
        ]
      },
      "output": {
        "cliente": "Acme Corporation",
        "valor": 150000
      }
    }
  ],
  "meta": {
    "totalCount": 142,
    "limit": 20,
    "offset": 0,
    "currentPage": 1,
    "totalPages": 8,
    "links": {
      "first": {
        "limit": 20,
        "offset": 0
      },
      "last": {
        "limit": 20,
        "offset": 140
      },
      "next": {
        "limit": 20,
        "offset": 20
      },
      "previous": null
    }
  }
}

POST

task

query

curl --request POST \
  --url https://api.tela.com/task/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "promptApplicationId": "95cec438-6080-44fe-8275-28b16bd40178",
  "filters": {
    "status": [
      "completed"
    ],
    "createdAtSince": "2025-01-01T00:00:00Z",
    "tags": [
      "priority"
    ]
  },
  "outputQuery": {
    "cliente": "Acme Corporation",
    "valor": {
      "$gte": 100000,
      "$lte": 500000
    },
    "lineItems": {
      "$elemMatch": {
        "amount": {
          "$gt": 1000
        }
      }
    }
  },
  "select": [
    "cliente",
    "valor"
  ],
  "orderBy": "createdAt",
  "order": "desc",
  "limit": 20,
  "offset": 0
}
'

{
  "data": [
    {
      "taskId": "8b6d2c9a-1f4e-4c1b-9a1e-3c2d5e6f7a80",
      "taskName": "Invoice-2025-001.pdf",
      "status": "completed",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "approvedAt": "2025-01-15T11:00:00.000Z",
      "input": {
        "variables": {
          "document": {
            "files": [
              {
                "file_url": "https://example.com/invoice.pdf",
                "file_name": "Invoice-2025-001.pdf",
                "mime_type": "application/pdf"
              }
            ]
          }
        },
        "messages": [],
        "files": [
          {
            "name": "document",
            "filename": "Invoice-2025-001.pdf",
            "url": "https://example.com/invoice.pdf",
            "usedAt": "variables",
            "mimeType": "application/pdf"
          }
        ]
      },
      "output": {
        "cliente": "Acme Corporation",
        "valor": 150000
      }
    }
  ],
  "meta": {
    "totalCount": 142,
    "limit": 20,
    "offset": 0,
    "currentPage": 1,
    "totalPages": 8,
    "links": {
      "first": {
        "limit": 20,
        "offset": 0
      },
      "last": {
        "limit": 20,
        "offset": 140
      },
      "next": {
        "limit": 20,
        "offset": 20
      },
      "previous": null
    }
  }
}

Query tasks from a Workstation (App) with powerful filtering capabilities. This endpoint allows you to filter by metadata (status, dates, tags) and by extracted data fields using MongoDB-style operators.

Basic Query

const API_KEY = process.env.TELA_API_KEY;

const response = await fetch('https://api.tela.com/task/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptApplicationId: "your-app-uuid",
    limit: 20
  })
});

const data = await response.json();
console.log(data);

import requests
import os

API_KEY = os.getenv('TELA_API_KEY')

response = requests.post(
    'https://api.tela.com/task/query',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'promptApplicationId': 'your-app-uuid',
        'limit': 20
    }
)

print(response.json())

const API_KEY = process.env.TELA_API_KEY;

fetch('https://api.tela.com/task/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptApplicationId: 'your-app-uuid',
    limit: 20
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Query with Metadata Filters

Filter tasks by status, creation date, approval date, tags, and more.

const response = await fetch('https://api.tela.com/task/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptApplicationId: "your-app-uuid",
    filters: {
      status: ["approved", "completed"],
      createdAtSince: "2025-01-01T00:00:00Z",
      createdAtUntil: "2025-01-31T23:59:59Z",
      approvedBy: ["user@company.com"],
      tags: ["priority", "reviewed"]
    },
    orderBy: "createdAt",
    order: "desc",
    limit: 50
  })
});

response = requests.post(
    'https://api.tela.com/task/query',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'promptApplicationId': 'your-app-uuid',
        'filters': {
            'status': ['approved', 'completed'],
            'createdAtSince': '2025-01-01T00:00:00Z',
            'createdAtUntil': '2025-01-31T23:59:59Z',
            'approvedBy': ['user@company.com'],
            'tags': ['priority', 'reviewed']
        },
        'orderBy': 'createdAt',
        'order': 'desc',
        'limit': 50
    }
)

Query by Extracted Data (outputQuery)

The most powerful feature is filtering by the data extracted from your documents. Use MongoDB-style operators to query any field in your task’s output.

Simple Equality

const response = await fetch('https://api.tela.com/task/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptApplicationId: "your-app-uuid",
    outputQuery: {
      "cliente": "Acme Corporation",
      "status": "active"
    }
  })
});

response = requests.post(
    'https://api.tela.com/task/query',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'promptApplicationId': 'your-app-uuid',
        'outputQuery': {
            'cliente': 'Acme Corporation',
            'status': 'active'
        }
    }
)

Comparison Operators

const response = await fetch('https://api.tela.com/task/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptApplicationId: "your-app-uuid",
    outputQuery: {
      // Numeric comparisons
      "valor": { "$gte": 100000, "$lte": 500000 },

      // Date comparisons
      "dataVencimento": { "$lte": "2025-03-31" },

      // Text search (case-insensitive)
      "descricao": { "$contains": "compliance" },

      // Value in list
      "categoria": { "$in": ["financeiro", "juridico"] }
    }
  })
});

response = requests.post(
    'https://api.tela.com/task/query',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'promptApplicationId': 'your-app-uuid',
        'outputQuery': {
            # Numeric comparisons
            'valor': { '$gte': 100000, '$lte': 500000 },

            # Date comparisons
            'dataVencimento': { '$lte': '2025-03-31' },

            # Text search (case-insensitive)
            'descricao': { '$contains': 'compliance' },

            # Value in list
            'categoria': { '$in': ['financeiro', 'juridico'] }
        }
    }
)

Querying Nested Arrays with $elemMatch

When your extracted data contains arrays (e.g., line items, categories, participants), use $elemMatch to query elements within those arrays.

$elemMatch supports nesting, so you can query deeply nested structures like categories[].items[].price.

// Example: Find menus that have any item under $10
const response = await fetch('https://api.tela.com/task/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptApplicationId: "your-app-uuid",
    outputQuery: {
      "categories": {
        "$elemMatch": {
          "items": {
            "$elemMatch": {
              "price": { "$lt": 10 }
            }
          }
        }
      }
    }
  })
});

# Example: Find menus that have any item under $10
response = requests.post(
    'https://api.tela.com/task/query',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'promptApplicationId': 'your-app-uuid',
        'outputQuery': {
            'categories': {
                '$elemMatch': {
                    'items': {
                        '$elemMatch': {
                            'price': { '$lt': 10 }
                        }
                    }
                }
            }
        }
    }
)

More $elemMatch Examples

// Find invoices with any line item over $1000
{
  "outputQuery": {
    "lineItems": {
      "$elemMatch": {
        "amount": { "$gt": 1000 }
      }
    }
  }
}

// Find contracts with a specific signatory
{
  "outputQuery": {
    "signatories": {
      "$elemMatch": {
        "name": { "$contains": "John" },
        "role": "CEO"
      }
    }
  }
}

// Find menus with vegan options in the beverages category
{
  "outputQuery": {
    "categories": {
      "$elemMatch": {
        "category_name": "BEVERAGES",
        "items": {
          "$elemMatch": {
            "dietary_tags": { "$contains": "Vegan" }
          }
        }
      }
    }
  }
}

Select Specific Fields

Reduce response size by selecting only the fields you need from the extracted data.

const response = await fetch('https://api.tela.com/task/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptApplicationId: "your-app-uuid",
    outputQuery: {
      "valor": { "$gt": 100000 }
    },
    select: ["cliente", "valor", "dataVencimento", "status"]
  })
});

response = requests.post(
    'https://api.tela.com/task/query',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'promptApplicationId': 'your-app-uuid',
        'outputQuery': {
            'valor': { '$gt': 100000 }
        },
        'select': ['cliente', 'valor', 'dataVencimento', 'status']
    }
)

Pagination

Use limit and offset for paginating through large result sets.

// First page
const page1 = await fetch('https://api.tela.com/task/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptApplicationId: "your-app-uuid",
    limit: 20,
    offset: 0
  })
});

// Second page
const page2 = await fetch('https://api.tela.com/task/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptApplicationId: "your-app-uuid",
    limit: 20,
    offset: 20
  })
});

Request Body

Field	Type	Required	Description
`promptApplicationId`	string	Yes	UUID of the Workstation/App to query
`filters`	object	No	Metadata filters (see below)
`outputQuery`	object	No	Filters on extracted data fields
`select`	string[]	No	Fields to return from output. If empty, returns all fields
`limit`	number	No	Max results to return (1-100, default: 50)
`offset`	number	No	Number of results to skip (default: 0)
`orderBy`	string	No	Sort field: `createdAt`, `updatedAt`, `approvedAt`, or `name`
`order`	string	No	Sort direction: `asc` or `desc`

Filters Object

Field	Type	Description
`status`	string[]	Filter by task status (e.g., `["approved", "completed"]`)
`createdAtSince`	string	Tasks created after this ISO datetime
`createdAtUntil`	string	Tasks created before this ISO datetime
`approvedAtSince`	string	Tasks approved after this ISO datetime
`approvedAtUntil`	string	Tasks approved before this ISO datetime
`approvedBy`	string[]	Filter by approver email addresses
`createdBy`	string[]	Filter by creator email addresses
`tags`	string[]	Filter by task tags

Output Query Operators

Operator	Example	Description
(none)	`"field": "value"`	Exact equality match
`$gt`	`{ "$gt": 100 }`	Greater than
`$gte`	`{ "$gte": 100 }`	Greater than or equal
`$lt`	`{ "$lt": 100 }`	Less than
`$lte`	`{ "$lte": 100 }`	Less than or equal
`$eq`	`{ "$eq": 100 }`	Explicit equality
`$ne`	`{ "$ne": 100 }`	Not equal
`$in`	`{ "$in": ["a", "b"] }`	Value in array
`$contains`	`{ "$contains": "text" }`	Case-insensitive text search
`$elemMatch`	`{ "$elemMatch": {...} }`	Match element in array
`$type`	`{ "$gt": "100", "$type": "number" }`	Override type inference

Type Inference

The system automatically infers data types from values:

Value Format	Inferred Type	SQL Cast
`100`, `3.14`	number	`::numeric`
`true`, `false`	boolean	`::boolean`
`"2025-03-01"`	date	`::date`
`"2025-03-01T10:00:00Z"`	timestamp	`::timestamp`
Other strings	string	(none)

Use $type to override when needed:

{ "codigo": { "$gt": "100", "$type": "number" } }

Response

{
  "data": [
    {
      "taskId": "550e8400-e29b-41d4-a716-446655440000",
      "taskName": "Invoice-2025-001.pdf",
      "status": "approved",
      "createdAt": "2025-01-15T10:30:00Z",
      "approvedAt": "2025-01-15T11:00:00Z",
      "output": {
        "cliente": "Acme Corporation",
        "valor": 150000,
        "dataVencimento": "2025-03-31"
      }
    }
  ],
  "meta": {
    "totalCount": 142,
    "limit": 20,
    "offset": 0,
    "currentPage": 1,
    "totalPages": 8
  }
}

Response Fields

Field	Type	Description
`data`	array	Array of matching tasks
`data[].taskId`	string	Unique task identifier
`data[].taskName`	string	Task name (usually the document filename)
`data[].status`	string	Current task status
`data[].createdAt`	string	ISO datetime when task was created
`data[].approvedAt`	string \| null	ISO datetime when task was approved
`data[].output`	object	Extracted data (all fields or selected fields)
`meta.totalCount`	number	Total number of matching tasks
`meta.limit`	number	Results per page
`meta.offset`	number	Number of results skipped
`meta.currentPage`	number	Current page number
`meta.totalPages`	number	Total number of pages

Error Responses

Status	Description
`400`	Invalid request body or malformed query
`401`	Missing or invalid data token
`403`	Token doesn’t have access to the specified app
`404`	App not found
`500`	Internal server error

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

By Workstation/App
By agent

Provide exactly one of promptApplicationId or agentId.

promptApplicationId

string<uuid>

required

Workstation/App ID to query tasks from.

filters

Metadata filters · object

Show child attributes

outputQuery

Output query · object

Map of field name → primitive value (equality; null is accepted) or operator object.

Show child attributes

select

string[]

Fields to return from outputContent.content. If empty or omitted, the full outputContent is returned.

limit

integer

default:50

Required range: 1 <= x <= 100

offset

integer

default:0

Required range: x >= 0

orderBy

enum<string>

default:createdAt

Available options:

createdAt,

updatedAt,

approvedAt,

name

order

enum<string>

default:desc

Available options:

asc,

desc

Response

Matching tasks

data

object[]

required

Show child attributes

Completion

Completion Run

File

Canvas

Prompt Version

Prompt Version Message

Environment

Test Case

Test Case Tag

Task

Webhook

Workflow Run

Query Tasks

Basic Query

Query with Metadata Filters

Query by Extracted Data (outputQuery)

Simple Equality

Comparison Operators

Querying Nested Arrays with $elemMatch

More $elemMatch Examples

Select Specific Fields

Request Body

Filters Object

Output Query Operators

Type Inference

Response

Response Fields

Error Responses

Authorizations

Body

Response

​Basic Query

​Query with Metadata Filters

​Query by Extracted Data (outputQuery)

​Simple Equality

​Comparison Operators

​Querying Nested Arrays with $elemMatch

​More $elemMatch Examples

​Select Specific Fields

​Pagination

​Request Body

​Filters Object

​Output Query Operators

​Type Inference

​Response

​Response Fields

​Error Responses

Authorizations

Body

Response

Basic Query

Query with Metadata Filters

Query by Extracted Data (outputQuery)

Simple Equality

Comparison Operators

Querying Nested Arrays with $elemMatch

More $elemMatch Examples

Select Specific Fields

Pagination

Request Body

Filters Object

Output Query Operators

Type Inference

Response

Response Fields

Error Responses