Find Time Entry

Overview

The Find Time Entry endpoint allows you to search for time entries with comprehensive filtering options. This endpoint supports advanced search criteria including date ranges, project/task filters, team member selection, and billable status filtering for detailed time tracking analysis.

This endpoint provides the most comprehensive filtering options among all find endpoints, allowing you to locate specific time entries based on multiple criteria for detailed time tracking and reporting workflows.

Authentication

All requests require a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

curl -X POST 'https://app.timetracker.in/api/integrations/zapier/triggers/time-entries/find' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321",
    "description": "Development work",
    "project_id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "billable": "true",
    "date_after": "2024-01-01T00:00:00Z",
    "date_before": "2024-01-31T23:59:59Z"
  }'

Request Body

workspace_id

string

required

The unique identifier of the workspace to search within. Must be a valid UUID format.Example: "w1b2c3d4-e5f6-7890-abcd-ef0987654321"

description

string

Search for time entries by description text. Performs case-insensitive partial matching.Example: "Development work" or "meeting" (will match entries containing these terms)

team_member_id

string

Filter time entries by specific team member ID.Example: "tm1a2b3c4-d5e6-7890-abcd-ef1234567890"

project_id

string

Filter time entries by specific project ID.Example: "p1a2b3c4-d5e6-7890-abcd-ef1234567890"

task_id

string

Filter time entries by specific task ID.Example: "t1a2b3c4-d5e6-7890-abcd-ef1234567890"

billable

string

Filter by billable status. Accepts "true" or "false".Example: "true" (only billable entries) or "false" (only non-billable entries)

manually_entered

string

Filter by entry method. Accepts "true" or "false".Example: "true" (manually entered) or "false" (tracked with timer)

date_after

string

Filter entries created after this date. Must be ISO 8601 format.Example: "2024-01-01T00:00:00Z"

date_before

string

Filter entries created before this date. Must be ISO 8601 format.Example: "2024-01-31T23:59:59Z"

start_time_after

string

Filter entries with start time after this date. Must be ISO 8601 format.Example: "2024-01-01T09:00:00Z"

start_time_before

string

Filter entries with start time before this date. Must be ISO 8601 format.Example: "2024-01-01T17:00:00Z"

end_time_after

string

Filter entries with end time after this date. Must be ISO 8601 format.Example: "2024-01-01T10:00:00Z"

end_time_before

string

Filter entries with end time before this date. Must be ISO 8601 format.Example: "2024-01-01T18:00:00Z"

duration_min

integer

Filter entries with duration greater than or equal to this value (in seconds).Example: 3600 (1 hour minimum)

duration_max

integer

Filter entries with duration less than or equal to this value (in seconds).Example: 28800 (8 hours maximum)

Response

Success Response

Returns an array containing the matching time entry object with comprehensive details, or an empty array if no match is found:

[
  {
    "id": "te1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "date": "2024-01-15T10:00:00.000Z",
    "description": "Development work on new feature",
    "start_time": "2024-01-15T09:00:00.000Z",
    "end_time": "2024-01-15T17:00:00.000Z",
    "duration": 28800,
    "duration_hours": 8,
    "billable": true,
    "manually_entered": false,
    "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321",
    "workspace_name": "Development Team",
    "team_member_id": "tm1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "team_member_name": "John Doe",
    "team_member_email": "[email protected]",
    "team_member_role": "Developer",
    "project_id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "project_name": "Mobile App Development",
    "project_status": "active",
    "client_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "client_name": "TechCorp Inc.",
    "task_id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "task_name": "Implement user authentication",
    "task_status": "in-progress",
    "timesheet_id": "ts1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "timesheet_status": "draft",
    "tags": [
      {
        "id": "tag1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "name": "Development",
        "color": "#3B82F6"
      }
    ],
    "tag_count": 1,
    "createdAt": "2024-01-15T09:00:00.000Z",
    "updatedAt": "2024-01-15T17:00:00.000Z"
  }
]

string

Unique time entry identifier (UUID format)

date

string

Date when the time entry occurred (ISO 8601 format)

description

string

Description of the work performed

start_time

string

Start time of the work session (ISO 8601 format, null if not tracked)

end_time

string

End time of the work session (ISO 8601 format, null if not tracked)

duration

integer

Duration of the work session in seconds

duration_hours

number

Duration of the work session in hours (calculated from seconds)

billable

boolean

Whether this time entry is billable to the client

manually_entered

boolean

Whether this entry was manually entered or tracked with a timer

workspace_id

string

Unique identifier of the workspace containing this time entry

workspace_name

string

Name of the workspace containing this time entry

team_member_id

string

Unique identifier of the team member who logged this time entry

team_member_name

string

Full name of the team member who logged this time entry

team_member_email

string

Email address of the team member who logged this time entry

team_member_role

string

Role name of the team member who logged this time entry

project_id

string

Unique identifier of the associated project (null if no project)

project_name

string

Name of the associated project (null if no project)

project_status

string

Status of the associated project (null if no project)

client_id

string

Unique identifier of the associated client (null if no client)

client_name

string

Name of the associated client (null if no client)

task_id

string

Unique identifier of the associated task (null if no task)

task_name

string

Name of the associated task (null if no task)

task_status

string

Status of the associated task (null if no task)

timesheet_id

string

Unique identifier of the associated timesheet (null if not part of a timesheet)

timesheet_status

string

Status of the associated timesheet (null if not part of a timesheet)

No Results Response

When no matching time entries are found, returns an empty array:

[]

Error Responses

400 Bad Request - Invalid Parameters

{
  "error": "Invalid request parameters"
}

Cause: Invalid UUID format, invalid date format, or invalid filter values
Solution: Ensure all parameters use correct formats (UUIDs, ISO 8601 dates, valid boolean strings)

401 Unauthorized

{
  "error": "Unauthorized"
}

Cause: Invalid or missing API key
Solution: Verify your API key is correct and properly formatted

500 Internal Server Error

{
  "error": "Internal server error"
}

Cause: Server-side error during search
Solution: Retry the request or contact support if the issue persists

Advanced Filtering Options

Date Range Filtering

The endpoint supports multiple date-based filters:

Entry Date Filtering

Fields: date_after, date_before
Purpose: Filter by when the time entry was created
Use Case: Find entries from specific time periods

Work Session Filtering

Fields: start_time_after, start_time_before, end_time_after, end_time_before
Purpose: Filter by actual work session times
Use Case: Find entries from specific work hours or shifts

Duration Filtering

Fields: duration_min, duration_max
Purpose: Filter by work session duration
Use Case: Find short breaks, long work sessions, or specific duration ranges

Project and Task Filtering

Filter time entries by their project or task associations:

Project Filtering: Use project_id to find all time entries for a specific project
Task Filtering: Use task_id to find all time entries for a specific task
Combined Filtering: Use both filters together for more specific results

Team Member Filtering

Filter time entries by the team member who logged them:

Individual Filtering: Use team_member_id to find entries for a specific team member
Team Analysis: Combine with date filters to analyze individual productivity

Billable and Entry Method Filtering

Filter by business-relevant criteria:

Billable Status: Use billable to separate billable from non-billable work
Entry Method: Use manually_entered to distinguish between timer-tracked and manually entered time

Zapier Integration Usage

Common Use Cases

Time Entry Analysis

Use Case: Analyze time tracking data for reporting, billing, or productivity analysis.Implementation: Use multiple filters to create detailed reports on time allocation, billable hours, or team productivity.

Billing and Invoicing

Use Case: Generate billing reports or create invoices based on billable time entries.Implementation: Filter by billable: "true" and date ranges to get billable hours for specific periods.

Project Time Tracking

Use Case: Monitor time spent on specific projects or tasks for project management.Implementation: Use project_id or task_id filters to track project progress and time allocation.

Team Productivity Monitoring

Use Case: Monitor team member productivity and work patterns.Implementation: Use team_member_id and date filters to analyze individual or team productivity.

Timesheet Management

Use Case: Manage timesheet submissions and approvals.Implementation: Use timesheet_id and timesheet_status to work with timesheet data.

Zapier Field Mapping

When setting up Zapier actions, you can map these time entry fields:

Time Entry ID → id (for referencing in other API calls)
Time Data → duration, duration_hours, start_time, end_time (for time calculations)
Work Information → description, date (for work documentation)
Billing Data → billable (for billing workflows)
Project/Task Data → project_id, project_name, task_id, task_name (for project association)
Team Member Data → team_member_id, team_member_name, team_member_email (for team management)
Client Data → client_id, client_name (for client association)
Tag Data → tags array, tag_count (for categorization)

Time Entry Types

Timer-Tracked Entries

Entries created using the timer feature:

Characteristics: Have start_time and end_time values
Manually Entered: false
Use Case: Real-time work tracking

Manually Entered Entries

Entries created by manually entering time:

Characteristics: May not have start_time and end_time values
Manually Entered: true
Use Case: Retroactive time entry or estimated time

Best Practices

Search Optimization:

Use specific date ranges to limit results and improve performance
Combine multiple filters for more precise results
Use description text search for finding specific types of work
Consider using duration filters to find unusual time entries
Cache frequently used filter combinations

Pro Tip: Use the comprehensive filtering options to create automated reports that analyze time allocation patterns, identify productivity trends, or generate client billing summaries.

Performance Considerations: When using multiple filters, especially date ranges, consider the time period to avoid returning too many results. Large result sets may impact performance.

Rate Limits

This endpoint follows standard API rate limiting:

Rate Limit: 100 requests per minute per API key
Burst Limit: 10 requests per second
Reset Period: Rolling 60-second window

Rate Limit Headers: Response headers include current usage information:

X-RateLimit-Limit: Maximum requests per window
X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: Timestamp when the limit resets

Health

Integrations

Find Time Entry

Overview

Authentication

Find Time Entry

Request Body

Response

Success Response

No Results Response

Error Responses

Advanced Filtering Options

Date Range Filtering

Project and Task Filtering

Team Member Filtering

Billable and Entry Method Filtering

Zapier Integration Usage

Common Use Cases

Zapier Field Mapping

Time Entry Types

Timer-Tracked Entries

Manually Entered Entries

Best Practices

Rate Limits

Health

Integrations

​Overview

​Authentication

​Find Time Entry

​Request Body

​Response

​Success Response

​No Results Response

​Error Responses

​Advanced Filtering Options

​Date Range Filtering

​Project and Task Filtering

​Team Member Filtering

​Billable and Entry Method Filtering

​Zapier Integration Usage

​Common Use Cases

​Zapier Field Mapping

​Time Entry Types

​Timer-Tracked Entries

​Manually Entered Entries

​Best Practices

​Rate Limits

Overview

Authentication

Find Time Entry

Request Body

Response

Success Response

No Results Response

Error Responses

Advanced Filtering Options

Date Range Filtering

Project and Task Filtering

Team Member Filtering

Billable and Entry Method Filtering

Zapier Integration Usage

Common Use Cases

Zapier Field Mapping

Time Entry Types

Timer-Tracked Entries

Manually Entered Entries

Best Practices

Rate Limits